Introduction

CLORE.AI api can be used to automate deployments of your workloads onto CLORE.AI

Firstly you need to get an API key
alt text
alt text


API responses

Responses are returned in JSON format, may have different fields

Always returned field is code, indicating status

code field

code Description
0 NORMAL
1 DATABASE ERROR
2 INVALID INPUT DATA
3 INVALID API TOKEN
4 INVALID ENDPOINT
5 EXCEEDED 1 request/second limit
6 Error specified in error field

Endpoints

1. wallets

About

Return wallets and balances

Headers

Field Type Mandatory Description
auth string Yes API token

Output

Field Type Description
code int Status code
wallets []string Array of wallets

Example

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/wallets'

Output:

{
  "wallets": [
    {
      "name": "bitcoin",
      "deposit": "tb1q6erw7v02t7hakgmlcl4wfnlykzqj05alndruwr",
      "balance": 0.00153176,
      "withdrawal_fee": 0.0001
    }
  ],
  "code": 0
}

2. my_servers

About

Returns your servers that you are providing to clore.ai marketplace

Headers

Field Type Mandatory Description
auth string Yes API token

Output

Field Type Description
code int Status code
limit int Maximum number of servers you can own
servers []string Array of servers
servers[x].name string User selected server name
servers[x].connected string Was the server ever connected to clore.ai
servers[x].visibility string Visibility on marketplace
servers[x].pricing []string Price/day on-demand
servers[x].online bool Is server online
servers[x].min_spot_pricing []string Minimal price/day to rent for on spot market
servers[x].init_token string Initialization token
servers[x].specs []string Server specifications

Example

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/my_servers'

Output:

{
  "servers": [
    {
      "name": "Michael",
      "connected": false,
      "visibility": "hidden",
      "pricing": { "bitcoin": 0, "usd": 0 },
      "online": false,
      "min_spot_pricing": { "bitcoin": 0, "usd": 0 },
      "init_token": "qnwVIMsZPjUWS7jw6gAbTOeoGQNgTH9XVxJaiCEbG0OlmfjF"
    },
    {
      "name": "Jan Vykydal",
      "connected": true,
      "visibility": "public",
      "pricing": { "bitcoin": 0.00010337, "usd": 0 },
      "online": false,
      "min_spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "Intel Core i9-11900",
        "cpus": "8/16",
        "ram": 64,
        "disk": "NVMe 512GB",
        "disk_speed": 2000,
        "gpu": "1x GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "down":119.61,
          "up":25.24
        }
      }
    }
  ],
  "limit": 16,
  "code": 0
}
*USD not implemented yet

3. server_config

About

Get configuration of specific server

Headers

Field Type Mandatory Description
auth string Yes API token
Content-type string Yes Must be application/json

Body

Field Type Mandatory Description
server_name string Yes Server name

Output

Field Type Description
code int Status code
creation_completed bool Is server creation complete
config []string Config of server
config.name string User selected server name
config.connected bool Was the server ever connected to clore.ai
config.visibility string Visibility on marketplace
config.pricing []string Price/day on-demand
config.spot_pricing []string Minimal price/day to rent for on spot market
config.mrl int Maximum rental length in hours
config.online bool Is server online
config.initialized bool Was the server ever connected to clore.ai
config.id int Unique server ID
config.rental_status int 0 - not rented | 1 - Rented on spot market | 2 - Rented On Demand
config.specs []string Server specifications
config.background_job []string Background job when not rented

Example

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "server_name":"Jan Vykydal"
}' 'https://api.clore.ai/v1/server_config'

Output:

{
  "config": {
    "name": "Jan Vykydal",
    "connected": true,
    "visibility": "public",
    "pricing": { "bitcoin": 0.00010337, "usd": 0 },
    "spot_pricing": { "bitcoin": 0.00005168, "usd": 0 },
    "mrl": 72,
    "online": false,
    "initialized": true,
    "id": 4,
    "rental_status": 0,
    "specs": {
      "mb": "Z590 GAMING X",
      "cpu": "Intel Core i9-11900",
      "cpus": "8/16",
      "ram": 64,
      "disk": "NVMe 512GB",
      "disk_speed": 2000,
      "gpu": "1x GeForce GTX 1080 Ti",
      "gpuram": 11,
      "net": {
        "down":119.61,
        "up":25.24
      }
    },
    "background_job": {
      "times_updated": 1,
      "image": "cloreai/ubuntu20.04-jupyter",
      "command": "",
      "env": []
    }
  },
  "creation_completed": true,
  "code": 0
}
*USD not implemented yet

4. marketplace

About

Get marketplace

Headers

Field Type Mandatory Description
auth string Yes API token

Output

Field Type Description
code int Status code
my_servers []string Array of server ids you are providing to clore.ai (can't be rented)
servers []string Array of public servers on marketplace
servers[x].id int Unique server ID
servers[x].owner int Unique owner ID
servers[x].mrl int Maximum rental length in hours
servers[x].price.on_demand []string On demand price per day
servers[x].spot []string Minimal spot market price per day
servers[x].rented bool Is server rented on demand
servers[x].specs []string Server specifications

Example

Get marketplace

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/marketplace'

Output:

{
  "servers": [
    {
      "id": 6,
      "owner": 4,
      "mrl": 73,
      "price": { "on_demand": { "bitcoin": 0.00001 },
      "spot": { "bitcoin": 0.000001 }},
      "rented": false,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 0,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "up": 26.38,
          "down": 118.42,
          "cc": "CZ"
        }
      }
    }
  ],
  "my_servers": [1, 2, 4],
  "code": 0
}

5. my_orders

About

Get your orders

Headers

Field Type Mandatory Description
auth string Yes API token

Query string

Field Type Mandatory Description
return_completed bool No Return completed (expired) orders

Output

Field Type Description
code int Status code
limit int Maximum count of active orders
orders []string Array of orders
orders[x].id int Unique order ID
orders[x].fee float Fee (%) paid to clore.ai
orders[x].creation_fee float Creation fee paid to clore.ai
orders[x].price float Order price (cost) per day
orders[x].mrl int Maximum order rental length in seconds
orders[x].image string Used docker image
orders[x].currency string Currency used for billing
orders[x].spend float Money spend on the order
orders[x].ct int Creation time (UNIX time)
orders[x].p int Currently used proxy cluster
orders[x].specs []string Server specifications
orders[x].si int Unique server ID
orders[x].pub_cluster []string Public endpoints with forwarded ports
orders[x].tcp_ports []string TCP port forwarding
orders[x].http_port string Container port forwarded through HTTPS proxy
orders[x].spot bool Indication that it is spot order
orders[x].expired bool Indication that the order has expired

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/my_orders?return_completed=true'

Output:

{
  "orders": [
    {
      "id": 38,
      "fee": 5,
      "creation_fee": 3e-7,
      "price": 0.00001,
      "mrl": 262800,
      "image": "cloreai/ubuntu20.04-jupyter",
      "currency": "bitcoin",
      "spend": 6.944444444444445e-9,
      "ct": 1667401396,
      "p": 1,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 2000,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "up": 26.38,
          "down": 118.42,
        }
      },
      "si": 6,
      "pub_cluster": [ "n1.c1.clorecloud.net", "n2.c1.clorecloud.net" ],
      "tcp_ports": [ "22:10000" ],
      "http_port": "8888"
    },{
      "id": 36,
      "fee": 2.5,
      "creation_fee": 1e-7,
      "price": 0.00001,
      "mrl": 262800,
      "image": "cloreai/ubuntu20.04-jupyter",
      "currency": "bitcoin",
      "spend": 1.3888888888888888e-7,
      "ct": 1667248597,
      "specs": {
        "mb": "Z590 GAMING X",
        "cpu": "11th Gen Intel(R) Core(TM) i9-11900 @ 2.50GHz",
        "cpus": "8/16",
        "ram": 62.67348861694336,
        "disk": "NVMe disk 247.3623046875GB",
        "disk_speed": 2000,
        "gpu": "1x NVIDIA GeForce GTX 1080 Ti",
        "gpuram": 11,
        "net": {
          "up": 26.38,
          "down": 118.42,
        }
      },
      "si": 6,
      "spot": true,
      "expired": true,
      "tcp_ports": []
    }
  ],
  "limit": 13,
  "code": 0
}

6. spot_marketplace

About

Get spot marketplace for specific server

Headers

Field Type Mandatory Description
auth string Yes API token

Query string

Field Type Mandatory Description
market int Yes Unique server ID

Output

Field Type Description
code int Status code
exists bool Verification that the market exists
market object Marketplace
market.offers array Rental offers for the server
market.offers[x].offer_id int Unique offer ID
market.offers[x].bid float Offered price per day
market.offers[x].active bool This offer is currently used
market.offers[x].my bool This offer is owned by me
market.server object Server information
market.server.min_pricing object Minimal offer price per day
market.server.mrl int Maximum rental length in seconds
market.server.visibility string You can create offers only when visibility is public
market.server.online bool Server is online

Input:

curl -XGET -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' 'https://api.clore.ai/v1/spot_marketplace?market=6'

Output:

{
  "market": {
    "offers": [
      {
        "offer_id": 39,
        "bid": 0.0000042,
        "active": true,
        "my": true
      }
    ],
    "server": {
      "min_pricing": {
        "bitcoin": 0.000001
      },
      "mrl": 262800,
      "visibility": "public",
      "online": true
    }
  },
  "exists": true,
  "code": 0
}

7. set_server_settings

About

Configure settings of server you are providing on clore.ai marketplace

Headers

Field Type Mandatory Description
auth string Yes API token
Content-type string Yes Must be application/json

Body

Field Type Mandatory Description
name string Yes User selected server name
availability bool Yes Can server be rented
mrl int Yes Maximum server rental length
on_demand float Yes Price per day for your server on demand
spot float Yes Minimum price per day for SPOT offer

Output

Field Type Description
code int Status code

Example

Let's create a send proof for a transaction sent from the current wallet.

Input:

curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "name": "Jan Vykydal",
    "availability":true,
    "mrl":96,
    "on_demand":0.0001,
    "spot":0.00000113
}' 'https://api.clore.ai/v1/set_server_settings'

Output:

{
  "code": 0
}

8. set_spot_price

About

Set price per day on your SPOT market offer

Headers

Field Type Mandatory Description
auth string Yes API token
Content-type string Yes Must be application/json

Body

Field Type Mandatory Description
order_id int Yes Unique offer ID
desired_price float Yes Your offered price per day

Example

Let's try to update spot market price

Input 1 (Step down was too big):

curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000200
}' 'https://api.clore.ai/v1/set_spot_price'

Possible output 1 (Step down was too big):
You can lower spot market offer price by max of 0.00000100 ₿

Field Type Description
code int Status code
error string Error description field
max_step float Lowest possible value to what you can currently lower price
{
    "error":"exceeded_max_step",
    "max_step":0.0000032,
    "code":6
}

Input 2 (Valid price step down):

curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000320
}' 'https://api.clore.ai/v1/set_spot_price'

Possible output 2 (Valid price step down):

{
    "code": 0
}

Input 3 (Lower price even more after sending Input 2):

curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "order_id":39,
    "desired_price":0.00000220
}' 'https://api.clore.ai/v1/set_spot_price

Possible output 3 (Lower price even more after sending Input 2):
You can lower spot price once in 600 seconds

Field Type Description
code int Status code
error string Error description field
time_to_lowering float Remaining time (sec) to next possibility to lower price
{
    "error":"can_lower_every_600_seconds",
    "time_to_lowering":513,
    "code":6
}

9. cancel_order

About

Set price per day on your SPOT market offer

Headers

Field Type Mandatory Description
auth string Yes API token
Content-type string Yes Must be application/json

Body

Field Type Mandatory Description
id int Yes Unique order/offer ID
issue string No If you have encountered any issues with the server you can report them to clore.ai team, maximum 2048 characters

Output

Field Type Description
code int Status code

Example

Cancel order/offer

Input:
In this example we are reporting issues with GPU #1, if you don't have issues, don't include issue field.
You can write any message to text field and we will investigate it

curl -XPOST -H 'auth: b8qwqRAL5W7YDyDJeB4XANVvKndbrrPk' -H "Content-type: application/json" -d '{
    "id":39,
    "issue":"GPU #1 Was overheating and throttling"
}' 'https://api.clore.ai/v1/cancel_order'

Output:

{
  "code": 0
}

10. create_order

About

You can create spot offer or on demand order with this endpoint
This endpoint also allows only 1 request in 5 seconds

Headers

Field Type Mandatory Description
auth string Yes API token
Content-type string Yes Must be application/json

Body

Field Type Mandatory Description
currency string Yes Currency name
image string Yes Valid image from dockerhub
renting_server int Yes ID of server you want to rent
type string Yes on-demand OR spot
spotprice float Depends Offering price per day on spot market, required when making spot order
ports object No Port forwarding configuration, max 5 records
env object No Environment variables, limited to 12000 characters in total when stringified.
Variable name - 128 symbols max
Variable value - 1536 symbols max
jupyter_token string No Jupyter token for images that has jupyter notebooks, maximum 32 characters *
ssh_key string No SSH key for images with SSH, maximum 3072 characters *
ssh_password string No SSH password for images with SSH, maximum 32 characters *
command string No Command will be run on server after order creation
required_price float No Specify price for what you want to start the order, if machine owner changes the price, then order will not start (on demand only)
autossh_entrypoint bool No Use clore.ai entrypoint, that autometically deploy SSH server and custom /root/onstart.sh script

* To fields marked with star you can only input characters from this regexp group /^[a-zA-Z0-9\s-=.@+/]+$/

Output

Field Type Description
code int Status code

Example

Input 1 (Create spot offer):

curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency":"bitcoin",
    "image":"cloreai/ubuntu20.04-jupyter",
    "renting_server":6,
    "type":"spot",
    "spotprice":0.000001,
    "ports":{
        "22":"tcp",
        "8888":"http"
    },
    "env":{
        "VARIABLE_NAME":"VARIABLE_VALUE",
    },
    "jupyter_token":"hoZluOjbCOQ5D5yH7R",
    "ssh_password":"Hpcj08ZaOpCbTmn1Eu",
    "command":"#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'

Output 1 (Create spot offer):

{
  "code":0
}

Input 2 (Create on demand order):

curl -XPOST -H 'auth: 6FcuR7ibcwKR1Z32lEFoSotzUUtzKO2H' -H "Content-type: application/json" -d '
{
    "currency":"bitcoin",
    "image":"cloreai/ubuntu20.04-jupyter",
    "renting_server":6,
    "type":"on-demand",
    "ports":{
        "22":"tcp",
        "8888":"http"
    },
    "env":{
        "VARIABLE_NAME":"VARIABLE_VALUE",
    },
    "jupyter_token":"hoZluOjbCOQ5D5yH7R",
    "ssh_password":"Hpcj08ZaOpCbTmn1Eu",
    "command":"#!/bin/sh\napt update -y && apt install htop"
}' 'https://api.clore.ai/v1/create_order'

Output 2 (Create on demand order):

{
  "code":0
}