API
💡 Python Developers: Use the official clore-ai 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 and CLI Reference.
🧭 Prefer a browsable reference? Open the interactive API docs at clore.ai/api-docs. Base URL for all endpoints on this page:
https://api.clore.ai/v1/.
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
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
auth
string
Yes
API token
Output
code
int
Status code
wallets
[]string
Array of wallets
Example
Input:
Output:
2. my_servers
About
Returns your servers that you are providing to clore.ai marketplace
Headers
auth
string
Yes
API token
Output
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].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
Machine-registration token, returned only until the machine is initialized — treat as a credential, it registers machines to your account
servers[x].specs
[]string
Server specifications
servers[x].remaining_time
int
Rental end time of the latest active order (ms epoch)
servers[x].rental_state
string
Aggregate GPU rental state: none, partial, or full
servers[x].rented_gpus
int
GPUs currently rented across active orders
servers[x].total_gpus
int
Total GPUs on the server
servers[x].rented_price_by_currency
object
Sum of active order prices keyed by currency
servers[x].update_channel
string
Hosting-agent update channel: stable or beta
servers[x].requested_channel
string
Channel switch requested from the web UI (present only when requested)
servers[x].target_backend_version
int
Backend version the current channel targets
The rental-state fields (
remaining_time,rental_state,rented_gpus,total_gpus,rented_price_by_currency) are present only while the server has an active order.
Example
Input:
Output:
USD values in pricing objects reflect the USD-based pricing mode where the host enabled it.
3. server_config
About
Get configuration of specific server
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
server_name
string
Yes
Server name
Output
code
int
Status code
creation_completed
bool
Is server creation complete
config
[]string
Config of server
config.name
string
User selected server name
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.id
int
Unique server ID
config.rental_status
int
0 - not rented | 1 - Rented on spot market | 2 - Rented On Demand | 3 - Fixed-USD rental
config.specs
[]string
Server specifications
config.background_job
object
Background job when not rented: image, command, env, times_updated
config.autoprice
object | string
Per-currency autopricing configuration (legacy string values "pow" / "usd" also occur)
config.usd_pricing
object
USD price targets — present only when USD autopricing is enabled
config.tenants
[]object
Active orders on the server: rental_type, currency, price, remaining_time, gpu_count
server_configalso returns the same rental-state and update-channel fields asmy_servers:remaining_time,rental_state,rented_gpus,total_gpus,rented_price_by_currency,update_channel,requested_channel,target_backend_version. In both endpoints the rental-state fields are present only while the server has an active order.
Example
Input:
Output:
USD values in pricing objects reflect the USD-based pricing mode where the host enabled it.
4. marketplace
About
Get marketplace
Headers
auth
string
Yes
API token
Output
code
int
Status code
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].price.spot
[]string
Minimal spot market price per day
servers[x].rented
bool
Is server rented on demand
servers[x].specs
[]string
Server specifications
servers[x].partial_gpu_rental
object | bool
false when partial rental is unavailable, otherwise { total_gpus, available_gpus, free_indices }
price.on_demandandprice.spotonly include the currencies each server actually accepts — a server without a price in some currency cannot be rented in it.
Example
Get marketplace
Input:
Output:
5. my_orders
About
Get your orders
Headers
auth
string
Yes
API token
Query string
return_completed
bool
No
Return completed (expired) orders
Output
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].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
Actual amount debited so far: accumulated rental value plus the renter base fee (after PoH reduction) and any extra fee; excludes the one-off creation fee
orders[x].gpu_count
int
Number of GPUs the order occupies (on-demand orders; equals the rig's total GPUs unless it is a partial rental)
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:
Output:
6. spot_marketplace
About
Get spot marketplace for specific server
Headers
auth
string
Yes
API token
Query string
market
int
Yes
Unique server ID
Output
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 (in the offer's currency)
market.offers[x].currency
string
Currency of the bid
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, per accepted currency
market.server.mrl
int
Maximum rental length in hours
market.server.visibility
string
You can create offers only when visibility is public
market.server.online
bool
Server is online
market.currency_rates_in_usd
object
Live USD rates used to compare bids across currencies
Offers can be placed in any currency the server accepts; competing bids are compared by their USD value (using
currency_rates_in_usd), not face value.⚠️ Changed in August 2026:
market.server.mrlis now returned in hours (previously seconds). A value that read262800now reads73.
Input:
Output:
7. set_server_settings
About
Configure settings of server you are providing on clore.ai marketplace
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
name
string
Yes
User selected server name
availability
bool
Yes
Can server be rented
mrl
int
Yes
Maximum server rental length in hours (6 to 3000)
bitcoin_on_demand
float
Yes
On-demand price in BTC per day
bitcoin_spot
float
Yes
Minimum spot price in BTC per day
CLORE-Blockchain_on_demand
float
No
On-demand price in CLORE per day
CLORE-Blockchain_spot
float
No
Minimum spot price in CLORE per day
USD-Blockchain_on_demand
float
No
On-demand price in USD per day
USD-Blockchain_spot
float
No
Minimum spot price in USD per day
enabled-bitcoin
bool
No*
Accept Bitcoin for this server
enabled-CLORE-Blockchain
bool
No*
Accept CLORE for this server
enabled-USD-Blockchain
bool
No*
Accept USD stablecoins for this server
autoprice
object
No
Per-currency autopricing: set a currency key (bitcoin, CLORE-Blockchain) to "usd" for USD-based autopricing or false for fixed pricing
usd_pricing
object
No
USD price targets per currency, e.g. { "bitcoin": { "on_demand": 10, "spot": 5 } } — used only for currencies with autoprice set to "usd"
* The accepted-currency list is rebuilt from the
enabled-*flags on every call. A currency without itsenabled-<currency>: trueflag (or without a valid price) is dropped from the server's accepted currencies — omitting all flags leaves the server unrentable in every currency. Always sendenabled-<currency>: truefor each currency you want to keep accepting.Per-day prices are capped per currency: 0.000001–0.1 BTC, 0.1–5,000,000 CLORE, 0.1–10,000 USD.
When a currency is autopriced in USD, its listed crypto price is derived from
usd_pricingat the live exchange rate (re-derived about every 10 minutes) and any<currency>_on_demand/<currency>_spotvalue sent for it is ignored. Theusd_pricingtargets are whole-server $/day figures validated against the USD range (0.1–1,000); out-of-range values clamp to the nearest bound.
Output
code
int
Status code
Example
Let's create a send proof for a transaction sent from the current wallet.
Input:
Output:
8. set_spot_price
About
Set price per day on your SPOT market offer
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
order_id
int
Yes
Unique offer ID
desired_price
float
Yes
Your offered price per day
A price below the server's current spot floor is rejected with the current minimum included:
A raise must be at least 1% above both your current bid and the server's top bid in the same currency (rounded up to the currency's precision, capped at the price ceiling). A smaller raise is rejected with the lowest accepted price:
Example
Let's try to update spot market price
Input 1 (Step down was too big):
Possible output 1 (Step down was too big): You can lower spot market offer price by max of 0.00000100 ₿
code
int
Status code
error
string
Error description field
max_step
float
Lowest possible value to what you can currently lower price
Input 2 (Valid price step down):
Possible output 2 (Valid price step down):
Input 3 (Lower price even more after sending Input 2):
Possible output 3 (Lower price even more after sending Input 2): You can lower spot price once in 600 seconds
code
int
Status code
error
string
Error description field
time_to_lowering
float
Remaining time (sec) to next possibility to lower price
9. cancel_order
About
Cancel an active order or spot offer
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
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
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
Output:
10. create_order
About
You can create spot offer or on demand order with this endpoint
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
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 12288 characters in total when stringified.
Variable name - 128 symbols max, must not contain -
Variable value - 1536 symbols max
Only the first 30 valid variables are kept; extras are silently dropped
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)
gpu_count
int
No
Number of GPUs to rent on servers that support partial rental. Omit to rent the whole rig. On-demand only, homogeneous rigs only
gpu_indices
[]int
No
0-based GPU slot indices to rent; length must equal gpu_count. Take free slots from partial_gpu_rental.free_indices. Omit to let the backend pick free GPUs automatically
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
code
int
Status code
Spot bids below the server's floor are rejected with the current minimum included, so you can retry immediately:
The floor is recomputed from live coin rates roughly every 10 minutes, so a price read off the marketplace listing can be slightly stale — always use the returned
min_pricefor the retry.When the server already has spot bids in the same currency, a new bid must be at least 1% above the top one (rounded up to the currency's precision, capped at the price ceiling). A lower bid is rejected with the lowest accepted price:
Example
Input 1 (Create spot offer):
Output 1 (Create spot offer):
Input 2 (Create on demand order):
Output 2 (Create on demand order):
11. renter_fees
About
Get the current fee configuration: base renter fees, PoH fee reduction settings, order creation fees, and your PoH balance
Headers
auth
string
Yes
API token
Output
code
int
Status code
renter_fees.on_demand
object
Base fee (%) per currency for on-demand orders
renter_fees.spot
object
Base fee (%) per currency for spot orders
poh_config.max_reduction_percent
int
Maximum base-fee reduction through PoH (%)
poh_config.max_poh_amount
int
PoH balance at which the maximum reduction is reached
creation_fees.on_demand
object
Order creation fee per currency
creation_fees.spot
object
Spot order creation fee per currency
poh_balance
float
Your PoH CLORE balance
Input:
Output:
12. cancel_orders
About
Cancel multiple orders at once (up to 256 per request)
Headers
auth
string
Yes
API token
Content-type
string
Yes
Must be application/json
Body
order_ids
[]int
Yes
Order IDs to cancel, maximum 256
Output
code
int
Status code
failed_to_cancel
[]int
Order IDs that could not be cancelled
Input:
Output:
13. poh_balance
About
Get your Proof of Holding balance: items, totals, and PoH Marketplace offer amounts
Headers
auth
string
Yes
API token
Output
code
int
Status code
items
[]object
Your PoH items with individual balances
balance.total
float
Total PoH balance across all items
balance.free_amount
float
PoH balance not committed to offers
balance.reward_amount
float
Balance eligible for rewards
balance.offers.rented_amount
float
Amount rented out to other users
balance.offers.rented_on_marketplace_amount
float
Amount listed on the PoH Marketplace
balance.offers.leased_amount
float
Amount leased from other users
Input:
Output:
14. server-config.json
About
Get static API configuration data. No authentication required
Input:
15. get_relay
About
Get TCP forwarding relay nodes for your detected country. No authentication required
Output
code
int
Status code
country
string
Detected country code
nodes
object
Available relay nodes
Input:
Last updated
Was this helpful?