API Reference

The ColabHive Builder API lets you discover and register compatible HuggingFace models, 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. Register a compatible 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.
• Account Preferences — read account settings and opt spare capacity into or out of Share Hive.
• 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 — optional 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 PATCH	/api/builder/v1/account/preferences	Account Preferences
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
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 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.

Optional webhook routes

The Builder API serves the webhook management route patterns below, and the published openapi.json includes them together with the delivery-history routes listed in Outbound Webhooks. Polling remains available.

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

ColabHive publishes two contracts because the public gateway and the control plane have different lifecycles. A route absent from Builder is not undocumented if it appears in the Orchestrator contract; clients must generate against the service they call.

Resource	Scope	URL
Builder OpenAPI 3.1	/api/builder/v1, /v1	/openapi.json
Orchestrator OpenAPI 3.1	/api/v1, including data-protection and placement attestation	/openapi-orchestrator.json
Builder Swagger UI	Builder	api.colabhive.com/api/builder/v1/docs
Builder ReDoc	Builder	api.colabhive.com/api/builder/v1/redoc
llm.txt / llms-full.txt	Documentation corpus	/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 migration

Runtime errors use the stable error.code, error.message, error.details, and error.request_id envelope. The Builder contract now types inference endpoints, task polling, training runs, metrics, artifacts and lifecycle responses, and maps validation failures to that same envelope. Some secondary catalog/action responses remain permissive while their response models are migrated; generate strict clients for the primary flows above and inspect the schema of a secondary operation before relying on closed-world fields.

---

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.