# API > 💡 **Python Developers:** Use the official [clore-ai Python SDK](https://docs.clore.ai/developers/python-sdk) instead of raw API calls. It handles authentication, rate limiting, retries, and error handling automatically. > > **Quick start:** `pip install clore-ai` — See the [Python SDK docs](https://docs.clore.ai/developers/python-sdk) and [CLI Reference](https://docs.clore.ai/developers/cli-guide).
### Introduction [CLORE.AI](http://clore.ai/) api can be used to automate deployments of your workloads onto [CLORE.AI](http://clore.ai/) Firstly you need to get an API key\ ![alt text](https://clore.ai/assets/html/api-export1.png)\ ![alt text](https://clore.ai/assets/html/api-export2.png) *** ### 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](http://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](http://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](http://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](http://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](http://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](http://clore.ai/) | | `orders[x].creation_fee` | `float` | Creation fee paid to [clore.ai](http://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](http://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](http://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 } ```