API Reference

The ColabHive Builder API lets you import any model from HuggingFace, use the curated base catalog, train and merge your own models, and run inference — all over one HTTP API.

Two things are true at once:

1. Import any HuggingFace model. POST /models/hf/search → GET /models/hf/{repo_id}/info → POST /models/hf/register. Registering creates a model_config + an inference_endpoint, and the model becomes callable (first request triggers a cold start). See Models API.
2. Use the curated base catalog. LLMs, specialists, tools, generative models, and trainable templates maintained by ColabHive. Discover them live — never hardcode a list — via GET /api/builder/v1/actions or GET /api/builder/v1/endpoints?visibility=public.

The catalog is data-driven and changes over time. This reference documents the contracts; for the current set of models and endpoints, always query the live discovery endpoints below.

---

Base URL

https://api.colabhive.com

• Builder API is mounted under /api/builder/v1 — e.g. https://api.colabhive.com/api/builder/v1/endpoints.
• OpenAI-compatible API is mounted under /v1 — e.g. https://api.colabhive.com/v1/chat/completions.

Protected requests authenticate with an API key. Public discovery and health exceptions are marked below and in the live OpenAPI document. See Authentication.

---

Endpoints

Discovery (no list is hardcoded)

Endpoint	Purpose
GET /api/builder/v1/inference/models	All models available for inference (base + registered), optionally with readiness. No auth.
GET /api/builder/v1/endpoints	Inference endpoints, filterable by source (catalog vs trained), owner, base_model, visibility, task_type, search.
GET /api/builder/v1/actions	Authenticated, account-aware view for plugins and agents (LLMs, specialists, tools, trained, generative).
GET /api/builder/v1/capabilities	Supported capability types.

Reference pages

• Authentication — API keys (hive_…), headers, account context.
• Datasets — upload and manage training datasets.
• Training — create, monitor, and manage training runs.
• Merge & Retrain — merge models/adapters, retrain-on-top, lineage, rename.
• Models — trained-model catalog, HuggingFace import, model registry, capabilities.
• Inference — run predictions on endpoints (sync/async), readiness, binary/multimodal I/O.
• OpenAI-Compatible API — POST /v1/chat/completions drop-in for OpenAI clients.
• Actions — discover and invoke any capability by slug (n8n, Zapier, MCP, LangChain).
• Quick Reference — the shortest path to a first request.
• Agent & LLM Integration — machine-readable resources, readiness-aware routing.
• Outbound Webhooks — private-preview terminal notifications for inference, Actions/MCP invocations, training runs, and merges.

Full endpoint index

Every route the gateway exposes. The Builder API is under /api/builder/v1; the OpenAI-compatible surface is under /v1. This mirrors the live openapi.json.

Method	Path	Reference
GET	/api/builder/v1/capabilities	Models → Capabilities
GET	/api/builder/v1/health	Service health
GET	/api/builder/v1/inference/health	Inference service health
POST	/api/builder/v1/models/hf/search	Models → HF search
GET	/api/builder/v1/models/hf/{repo_id}/info	Models → HF info
POST	/api/builder/v1/models/hf/register	Models → HF register
GET	/api/builder/v1/models/registry	Models → List registry
PATCH	/api/builder/v1/models/registry/{model_config_id}/lifecycle	Models → Update lifecycle
POST GET	/api/builder/v1/models	Models → Trained models
GET	/api/builder/v1/models/{model_id}	Models → Get model
GET	/api/builder/v1/models/{model_id}/versions	Models → List versions
GET	/api/builder/v1/models/{model_id}/lineage	Merge & Retrain → Lineage
PATCH	/api/builder/v1/models/{model_id}/versions/{version_id}	Merge & Retrain → Rename
POST GET	/api/builder/v1/datasets	Datasets
POST	/api/builder/v1/datasets/upload	Datasets → Direct upload
GET DELETE	/api/builder/v1/datasets/{dataset_id}	Datasets
POST	/api/builder/v1/datasets/{dataset_id}/uploads/init	Datasets → Multipart
POST	/api/builder/v1/datasets/{dataset_id}/uploads/{upload_id}/commit	Datasets → Multipart
POST GET	/api/builder/v1/training/runs	Training
GET DELETE	/api/builder/v1/training/runs/{run_id}	Training → Get run
GET	/api/builder/v1/training/runs/{run_id}/logs	Training → Logs
GET	/api/builder/v1/training/runs/{run_id}/metrics	Training → Metrics
GET	/api/builder/v1/training/runs/{run_id}/events	Training → Events
GET	/api/builder/v1/training/runs/{run_id}/artifacts	Training → Artifacts
GET	/api/builder/v1/training/runs/{run_id}/artifacts/download-urls	Training → Download URLs
POST	/api/builder/v1/training/runs/{run_id}/cancel	Training → Cancel
POST	/api/builder/v1/training/runs/{run_id}/register-for-inference	Training → Register
POST	/api/builder/v1/training/merges	Merge & Retrain → Merge
GET	/api/builder/v1/training/model-configs	Training → Model configs
GET	/api/builder/v1/training/model-configs/{model_id}	Training → Get config
GET	/api/builder/v1/training/model-configs/{model_id}/schema	Training → Config schema
GET	/api/builder/v1/inference/models	Inference → List models
GET	/api/builder/v1/endpoints	Inference → List endpoints
GET DELETE	/api/builder/v1/endpoints/{endpoint_id}	Inference → Get/Delete
POST	/api/builder/v1/endpoints/{endpoint_id}/infer	Inference → Predictions
POST	/api/builder/v1/endpoints/{endpoint_id}/infer:async	Inference — HTTP 202 + task_id
POST	/api/builder/v1/endpoints/{endpoint_id}/upload-input	Inference → Binary input
GET	/api/builder/v1/tasks/{task_id}	Inference → Poll task
GET	/api/builder/v1/queue/stats	Inference → Queue stats
GET	/api/builder/v1/actions	Actions → Discover
GET	/api/builder/v1/actions/{slug}	Actions → Detail
POST	/api/builder/v1/actions/{slug}:invoke	Actions → Invoke
GET	/api/builder/v1/invocations/{invocation_id}	Actions → Poll
GET	/api/builder/v1/mcp/manifest · /mcp/manifest/{slug}	MCP Tools Reference
POST	/v1/chat/completions	OpenAI-Compatible API
GET	/v1/models	OpenAI-Compatible API
GET	/v1/models/{model}	OpenAI-Compatible API

Token-by-token streaming lives here: POST /v1/chat/completions with "stream": true returns real SSE and works with unmodified OpenAI clients. There is no :stream route on the typed inference surface.

Private-preview candidate routes

The feature-on candidate adds only the four route patterns below. They are intentionally absent from the default published openapi.json and are not a claim of live availability.

Methods	Path	Reference
POST GET	/api/builder/v1/webhook-endpoints	Outbound Webhooks
GET PATCH DELETE	/api/builder/v1/webhook-endpoints/{endpoint_id}	Outbound Webhooks
POST	/api/builder/v1/webhook-endpoints/{endpoint_id}/rotate-secret	Outbound Webhooks
POST	/api/builder/v1/webhook-endpoints/{endpoint_id}/test	Outbound Webhooks

---

Machine-readable specs

Resource	URL
OpenAPI 3.1	/openapi.json
Swagger UI	api.colabhive.com/api/builder/v1/docs
ReDoc	api.colabhive.com/api/builder/v1/redoc
llm.txt / llms-full.txt	/llm.txt · /llms-full.txt

The published openapi.json is regenerated from the live gateway and reflects the real routes, including /v1/chat/completions and /api/builder/v1/training/merges.

Response-schema limitation

Runtime errors use the stable error.code, error.message, error.details, and error.request_id envelope. The generated OpenAPI still describes validation errors with FastAPI's legacy HTTPValidationError schema and many success responses as untyped objects. Until those generated schemas are corrected in the gateway, treat the runtime examples in this reference as authoritative for response bodies; do not generate strict response clients from those incomplete schemas.

---

Python SDK

pip install colabhive

from colabhive import ColabHive

client = ColabHive(
    api_key="hive_...",          # or set COLABHIVE_API_KEY
    account_id="your_account_id" # optional; auto-detected from the key
)

The base URL defaults to https://api.colabhive.com (override with COLABHIVE_BASE_URL or the base_url= argument). See the SDK Reference for the full surface.