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)

---

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"

---

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

---

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"])

---

Rate Limits

Rate limiting is enforced at the infrastructure layer (Nginx); exceeding it returns HTTP 429. Published per-plan tiers and X-RateLimit-* headers are roadmap — 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
429	Rate limit exceeded
500	Internal server error

---

Next Steps

• LLM Models
• Tools
• Specialists
• Full API Reference