# 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](/reference/clore-client.md) for the full implementation and setup instructions. Save it as `clore_client.py` in your project. ```python from clore_client import CloreClient client = CloreClient(api_key="your-api-key") ``` ## Authentication All requests require the `auth` header: ```bash curl -H "auth: YOUR_API_KEY" https://api.clore.ai/v1/marketplace ``` **Note:** The header is `auth`, NOT `Authorization: Bearer`! ```` ## 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. ```python 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 ```bash GET /v1/wallets ``` Returns wallet balances for all currencies. ```python 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 ```bash POST /v1/create_order ``` Rent a server. ```python 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 ```bash GET /v1/my_orders GET /v1/my_orders?return_completed=true ``` ```python 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 ```bash POST /v1/cancel_order ``` ```python response = requests.post( "https://api.clore.ai/v1/cancel_order", headers=headers, json={"id": order_id} ) ``` ### Update Spot Price ```bash POST /v1/set_spot_price ``` ```python 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 ```bash GET /v1/spot_marketplace?market=SERVER_ID ``` ```python 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 ```python import requests import time # Usage client = CloreClient("YOUR_API_KEY") servers = client.get_marketplace() ``` ## Server Object Structure ```python { "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 ```python { "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 root@node123.clore.ai -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](/reference/error-codes.md) * [Docker Images Reference](/reference/docker-images.md) * [Quick Start Guide](/getting-started/quick-start.md) --- # 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://dev.clore.ai/reference/api-reference.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.