api

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

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
}

Introduction

API responses

code field

Endpoints

1. wallets

About

Headers

Output

Example

2. my_servers

About

Headers

Output

Example

*USD not implemented yet

3. server_config

About

Headers

Body

Output

Example

*USD not implemented yet

4. marketplace

About

Headers

Output

Example

5. my_orders

About

Headers

Query string

Output

6. spot_marketplace

About

Headers

Query string

Output

7. set_server_settings

About

Headers

Body

Output

Example

8. set_spot_price

About

Headers

Body

Example

9. cancel_order

About

Headers

Body

Output

Example

10. create_order

About

Headers

Body

Output

Example

1. `wallets`

2. `my_servers`

3. `server_config`

4. `marketplace`

5. `my_orders`

6. `spot_marketplace`

7. `set_server_settings`

8. `set_spot_price`

9. `cancel_order`

10. `create_order`