# API > 💡 **Python Developers:** Use the official [clore-ai Python SDK](/developers/python-sdk.md) 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](/developers/python-sdk.md) and [CLI Reference](/developers/cli-guide.md).
### 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 } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.clore.ai/for-hosts/api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.