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

---

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
}