API Quick Reference

Quick reference for the most commonly used Clore.ai API endpoints.

Step 1: Set Up the Clore Client

📦 Using the standard Clore API client. See Clore API Client Reference for the full implementation and setup instructions. Save it as clore_client.py in your project.

from clore_client import CloreClient

client = CloreClient(api_key="your-api-key")

Authentication

All requests require the auth header:

curl -H "auth: YOUR_API_KEY" https://api.clore.ai/v1/marketplace

Note: The header is auth, NOT Authorization: Bearer! https://api.clore.ai

## Rate Limiting

- **1 request per second** per API key
- Implement exponential backoff when you receive code 5

## Common Endpoints

### Get Marketplace

```bash
GET /v1/marketplace

Returns all available servers with specs and pricing.

import requests

headers = {"auth": "YOUR_API_KEY"}
response = requests.get("https://api.clore.ai/v1/marketplace", headers=headers)
servers = response.json()["servers"]

# Filter available RTX 4090s
available = [s for s in servers 
             if not s["rented"] 
             and "RTX 4090" in str(s.get("gpu_array", []))]

Get Wallets

GET /v1/wallets

Returns wallet balances for all currencies.

response = requests.get("https://api.clore.ai/v1/wallets", headers=headers)
wallets = response.json()["wallets"]

# Get CLORE balance
clore_balance = next(w["balance"] for w in wallets if "CLORE" in w["name"])

Create Order

POST /v1/create_order

Rent a server.

order_data = {
    "renting_server": 12345,           # Server ID
    "type": "on-demand",               # or "spot"
    "currency": "CLORE-Blockchain",    # or "bitcoin", "USD-Blockchain"
    "image": "nvidia/cuda:12.8.0-base-ubuntu22.04",
    "ports": {"22": "tcp", "8888": "http"},
    "env": {"NVIDIA_VISIBLE_DEVICES": "all"},
    "ssh_password": "YourSecurePass123!"
}

# For spot orders, add:
# order_data["spotprice"] = 0.15

response = requests.post(
    "https://api.clore.ai/v1/create_order",
    headers=headers,
    json=order_data
)
order_id = response.json()["order_id"]

Get Orders

GET /v1/my_orders
GET /v1/my_orders?return_completed=true

response = requests.get("https://api.clore.ai/v1/my_orders", headers=headers)
orders = response.json()["orders"]

# Find active orders
active = [o for o in orders if o["status"] == "running"]

Cancel Order

POST /v1/cancel_order

response = requests.post(
    "https://api.clore.ai/v1/cancel_order",
    headers=headers,
    json={"id": order_id}
)

Update Spot Price

POST /v1/set_spot_price

response = requests.post(
    "https://api.clore.ai/v1/set_spot_price",
    headers=headers,
    json={
        "order_id": order_id,
        "desired_price": 0.20
    }
)

Get Spot Market

GET /v1/spot_marketplace?market=SERVER_ID

response = requests.get(
    "https://api.clore.ai/v1/spot_marketplace",
    headers=headers,
    params={"market": 12345}
)
spot_data = response.json()["market"]

Response Codes

Code	Meaning
0	Success
1	Database error
2	Invalid input
3	Invalid/missing API key
4	Invalid endpoint
5	Rate limit exceeded
6	See error field

Common Errors

Error	Solution
not_enough_balance	Top up your wallet
server-already-rented	Server not available
too_low_price	Increase spot bid
server-offline	Server is offline, try another
currency-not-allowed	Use different currency

Quick Python Client

import requests
import time

# Usage
client = CloreClient("YOUR_API_KEY")
servers = client.get_marketplace()

Server Object Structure

{
    "id": 12345,
    "owner": 67890,
    "mrl": 168,                     # Max rental hours
    "rented": False,
    "price": {
        "on_demand": {
            "bitcoin": 0.00000125,
            "CLORE-Blockchain": 0.25,
            "USD-Blockchain": 0.40
        },
        "spot": {
            "bitcoin": 0.0000008,
            "CLORE-Blockchain": 0.15
        },
        "usd": {
            "on_demand_clore": 0.40,  # USD per hour
            "spot": 0.25
        }
    },
    "specs": {
        "gpu": "2x NVIDIA GeForce RTX 4090",  # count prefix + full vendor name
        "cpu": "Intel i9-13900K",
        "ram": 64.0,                           # float, value in GB
        "disk": "SAMSUNG SSD SM841 2000GB"     # raw string
    },
    # Note: gpu count = len(gpu_array); use gpu_array for per-card model matching
    "gpu_array": ["NVIDIA GeForce RTX 4090", "NVIDIA GeForce RTX 4090"],
    "reliability": 0.985,  # float 0.0–1.0 (fraction, not percentage; e.g. 0.985 = 98.5% uptime)
    "rating": {"avg": 4.8, "cnt": 25},
    "allowed_coins": ["bitcoin", "CLORE-Blockchain", "USD-Blockchain"]
}

Order Object Structure

{
    "order_id": 98765,
    "renting_server": 12345,
    "type": "on-demand",
    "status": "running",           # pending, running, paused, expired
    "currency": "CLORE-Blockchain",
    "price": 0.25,
    "created": 1709400000,         # Unix timestamp
    "started": 1709400120,
    "connection": {
        "ssh": "ssh [email protected] -p 40022",
        "jupyter": "http://node123.clore.ai:8888",
        "ports": {
            "22": "tcp://node123.clore.ai:40022",
            "8888": "http://node123.clore.ai:40088"
        }
    }
}

See Also

• Common Error Codes

• Docker Images Reference

• Quick Start Guide