API Quick Reference

Real endpoints and authentication for ColabHive API

---

Base URL

https://api.colabhive.com

All inference endpoints are under /api/builder/v1/endpoints/{endpoint_id}/infer

---

Authentication

Required Headers

Header	Description	Example
X-API-Key	API key (required). Alternatively Authorization: Bearer hive_...	hive_...
X-Account-ID	Optional; if sent, must match the API key's account	YOUR_ACCOUNT_ID
Content-Type	application/json for POST requests	application/json

Where to Find Your Account ID

1. Log in to console.colabhive.com
2. Go to Settings → Account
3. Copy your Account ID (UUID format)

---

Share Hive Account Preference

Share Hive spare-capacity lending is disabled by default. Any authenticated account member can read the effective setting; only the account owner can change it.

curl "https://api.colabhive.com/api/builder/v1/account/preferences" \
  -H "X-API-Key: YOUR_API_KEY"

curl -X PATCH "https://api.colabhive.com/api/builder/v1/account/preferences" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"share_hive_opt_in": true}'

The account is derived from the credential; there is no request field for selecting a different lender account. Send false to opt out again.

---

Inference Endpoint

URL Pattern

POST https://api.colabhive.com/api/builder/v1/endpoints/{endpoint_id}/infer

Request Body

{
  "input": {
    // Your input data here
  }
}

Response

Inference is synchronous by default (sync: true). When the model is already loaded (resident), you get the result directly:

{
  "task_id": "uuid",
  "status": "succeeded",
  "model_state": "resident",
  "result": { "...": "..." },
  "sync_latency_ms": 245.5,
  "message": "Inference completed"
}

If the model is cold, the same call falls back to queuing — poll the task until it completes:

{
  "task_id": "uuid",
  "status": "queued",
  "note": "Task queued. Poll GET /api/builder/v1/tasks/{task_id} for results"
}

Poll Task Result

curl -X GET "https://api.colabhive.com/api/builder/v1/tasks/{TASK_ID}" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Branch on state (queued | running | succeeded | failed). While a task is queued, reason_code says why it is waiting and deferred_since since when; it is still progressing, so keep polling. On failed, failure_origin says whether the platform (platform) or the model (model) produced the outcome, or unattributed; platform_refusal: true marks a request the platform never executed. Infer answers and invocation polls carry the same fields. All fields: Get Task Result.

---

Discover Public Endpoints

List All Public Endpoints

Recommended: Always discover endpoints dynamically instead of hardcoding IDs.

# List all public LLMs
curl -X GET "https://api.colabhive.com/api/builder/v1/endpoints?visibility=public&task_type=chat" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# List all public tools
curl -X GET "https://api.colabhive.com/api/builder/v1/endpoints?visibility=public&task_type=tool" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Search by name
curl -X GET "https://api.colabhive.com/api/builder/v1/endpoints?visibility=public&search=mistral" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "endpoints": [
    {
      "endpoint_id": "uuid",
      "name": "mistral-7b-instruct-public",
      "display_name": "Mistral 7B Instruct",
      "task_type": "chat",
      "visibility": "public",
      "review_status": "approved",
      "price_per_request": 0.003
    }
  ],
  "total": 1
}

Categories

Category	Task Type	Examples
LLMs	chat, code	Mistral, Qwen, Llama, Gemma, DeepSeek
Tools	tool	web.fetch, web.search, web.scrape, geo.geocode
Specialists	specialist	embeddings, rerank, translate, ocr, moderate
Scorer	clm	CLM-8B: typed questions and ranking, no text generation

---

Example: Chat with LLM

Step 1: Discover Endpoint

# Find Mistral 7B endpoint
curl -X GET "https://api.colabhive.com/api/builder/v1/endpoints?visibility=public&search=mistral" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Step 2: Infer

# Use endpoint_id from discovery response
curl -X POST https://api.colabhive.com/api/builder/v1/endpoints/{ENDPOINT_ID}/infer \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "messages": [
        {"role": "user", "content": "What is machine learning?"}
      ],
      "max_tokens": 500,
      "temperature": 0.7
    }
  }'

Python SDK (Recommended)

from colabhive import ColabHive

client = ColabHive(
    api_key="YOUR_API_KEY",
    account_id="YOUR_ACCOUNT_ID",
    base_url="https://api.colabhive.com"
)

# Find endpoint by name (auto-discovery)
result = client.endpoints.infer(
    endpoint_id="mistral-7b-instruct-public",  # SDK auto-resolves name → endpoint_id
    input_data={
        "messages": [
            {"role": "user", "content": "What is machine learning?"}
        ],
    }
)

print(result)

---

Example: Use Tool

Step 1: Discover Tool

# Find web.fetch tool
curl -X GET "https://api.colabhive.com/api/builder/v1/endpoints?visibility=public&task_type=tool&search=web.fetch" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Step 2: Infer

# Use endpoint_id from discovery response
curl -X POST https://api.colabhive.com/api/builder/v1/endpoints/{ENDPOINT_ID}/infer \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "url": "https://example.com",
      "output_format": "markdown"
    }
  }'

Python SDK (Recommended)

from colabhive import ColabHive

client = ColabHive(
    api_key="YOUR_API_KEY",
    account_id="YOUR_ACCOUNT_ID",
    base_url="https://api.colabhive.com"
)

# Find tool by name (auto-discovery)
result = client.endpoints.infer(
    endpoint_id="web-fetch-public",  # SDK auto-resolves name
    input_data={
        "url": "https://example.com",
        "output_format": "markdown"
    }
)

print(result["output"]["content"])

---

Example: Score with CLM

CLM-8B generates no text: it answers typed questions about a state (/v1/systemone) or ranks candidate answers (/v1/rank). Both routes are at the API root, not under /api/builder/v1; model is the endpoint id or label.

curl -X POST https://api.colabhive.com/v1/systemone \
  -H "Authorization: Bearer $COLABHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "clm-v0.1-8b",
       "state": "Customer: my invoice was charged twice!",
       "questions": {"department": {"type": "choice", "instructions": "Which team?",
                                    "criteria": {"billing": "Charges and refunds", "technical": "Bugs"}}}}'

curl -X POST https://api.colabhive.com/v1/rank \
  -H "Authorization: Bearer $COLABHIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "clm-v0.1-8b", "context": "Tides are caused mainly by",
       "question": "Which answer completes the sentence?",
       "answers": ["the gravity of the Moon", "the wind over the ocean"]}'

Limits per request: 256 candidates, 64 questions, 32768 encoder tokens; over them, 413. See the OpenAI-compatible API for every field and error.

---

Rate Limits

Rate limiting is enforced at the infrastructure layer (Nginx); exceeding it returns HTTP 429. Plan limits are published at colabhive.com/pricing. X-RateLimit-* response headers are not emitted, so clients must handle 429 directly. See Authentication → Rate limits.

---

Error Codes

Code	Meaning
401	Unauthorized (missing or invalid API key)
403	Forbidden (no access to endpoint)
404	Endpoint not found
413	Request over a per-request limit (for example a CLM request with more than 256 candidates)
429	Rate limit exceeded
500	Internal server error

---

Next Steps

• LLM Models
• Tools
• Specialists
• Full API Reference