Models API

Import models from HuggingFace, browse the model registry, and manage your trained models. All endpoints require an API key (see Authentication); the account is auto-detected from the key.

Base URL: https://api.colabhive.com/api/builder/v1

Two different "register" flows

• Import from HuggingFace — POST /models/hf/register (this page). Turns any HF repo into a callable endpoint. Today these imports always land as public, base, free (see below).
• Register a trained model — POST /training/runs/{run_id}/register-for-inference (see Training API). Publishes a model you trained on ColabHive, with your choice of visibility and pricing subject to review.

---

HuggingFace Model Discovery

Search, inspect, and register any model from the HuggingFace Hub as an inference endpoint.

Search HuggingFace models

POST /models/hf/search

Request:

{
  "query": "embedding model",
  "task_type": "embeddings",
  "max_size_gb": 2.0,
  "license": ["apache-2.0", "mit"],
  "min_downloads": 1000,
  "limit": 20,
  "only_supported": true
}

Field	Type	Notes
query	string	Required. Free-text search.
task_type	string	ColabHive task vocabulary (see below). Optional.
max_size_gb	number	0.1–50. Optional.
license	string[]	Allowed licenses, e.g. apache-2.0, mit. Optional.
min_downloads	int	Minimum download count. Optional.
limit	int	Default 20, max 50.
only_supported	bool	Default true — only models compatible with a ColabHive runtime.

task_type values (ColabHive vocabulary, not HF pipeline tags): embeddings · rerank · translation · ocr · stt · moderation · text-generation. A HuggingFace-style pipeline tag (e.g. feature-extraction) will not match the mapping and the filter is silently ignored — use the values above.

Response:

{
  "results": [
    {
      "repo_id": "sentence-transformers/all-MiniLM-L6-v2",
      "task_type": "embeddings",
      "downloads": 50000000,
      "likes": 12000,
      "size_mb": 90,
      "license": "apache-2.0",
      "architectures": ["BertModel"],
      "framework": "sentence-transformers",
      "compatibility": {
        "status": "compatible",
        "runtime_profile_id": "specialist-cpu-optimized",
        "checks": []
      },
      "metadata": {}
    }
  ]
}

compatibility.status values: compatible · requires_review · incompatible.

Python SDK (search returns a list of dataclasses — use attribute access, not []):

results = client.models.hf.search(query="embedding model", task_type="embeddings", max_size_gb=2)
for m in results:
    print(m.repo_id, m.size_mb, "MB —", m.compatibility.status)

---

Get HuggingFace model info

GET /models/hf/{repo_id}/info

repo_id must be URL-encoded (/ → %2F). Returns the model card, config, file list, compatibility, and estimated resource requirements.

Example:

curl "https://api.colabhive.com/api/builder/v1/models/hf/sentence-transformers%2Fall-MiniLM-L6-v2/info" \
  -H "X-API-Key: hive_..."

Response:

{
  "repo_id": "sentence-transformers/all-MiniLM-L6-v2",
  "model_card": { "...": "..." },
  "config": { "architectures": ["BertModel"], "...": "..." },
  "size_mb": 90,
  "files": ["config.json", "model.safetensors", "..."],
  "compatibility": {
    "status": "compatible",
    "runtime_profile_id": "specialist-cpu-optimized",
    "checks": []
  },
  "estimated_requirements": { "vram_mb": 512, "...": "..." }
}

Python SDK:

info = client.models.hf.info("sentence-transformers/all-MiniLM-L6-v2")
print(info.compatibility.status, info.size_mb)

---

Register a HuggingFace model

POST /models/hf/register

Registers a HuggingFace repo as an inference endpoint. On success it creates a model_config and an inference_endpoint; the model is callable on its first request (cold start).

Request:

{
  "repo_id": "sentence-transformers/all-MiniLM-L6-v2",
  "task_type": "embeddings",
  "hf_revision": "main",
  "lifecycle_status": "candidate",
  "display_name": "MiniLM Embeddings",
  "description": "Lightweight sentence embeddings"
}

Field	Type	Notes
repo_id	string	Required.
task_type	string	Required. ColabHive task vocabulary (see search).
hf_revision	string	Commit / tag / branch. Default main.
runtime_profile_id	string	Override the auto-detected runtime profile. Optional.
resource_requirements	object	Override the estimated requirements. Optional.
gguf_file	string	For GGUF (CPU-LLM) repos: the specific .gguf file to serve. Optional.
lifecycle_status	string	Initial status. Only candidate is accepted during import; promotion happens later through the lifecycle endpoint.
visibility	string	Optional, but only the literal public is accepted. Any other value returns HTTP 422.
tags	string[]	For discovery. Optional.
display_name	string	UI label. Optional.
description	string	Optional.

HF imports only accept public candidate registration

HuggingFace imports are registered as public, candidate, is_base_model = true, and price_per_request = 0 (free). The request schema accepts only visibility="public" and lifecycle_status="candidate"; other values return HTTP 422 instead of being silently ignored. If you need a private, priced model, train and register it via register-for-inference instead.

Response:

{
  "model_config_id": "0e2f1a3b-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
  "endpoint_id": "9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d",
  "repo_id": "sentence-transformers/all-MiniLM-L6-v2",
  "status": "registered",
  "message": "Model registered and endpoint created",
  "inference_url": "/api/builder/v1/endpoints/9b8a7c6d-5e4f-3a2b-1c0d-9e8f7a6b5c4d/infer",
  "test_request": { "input": { "text": "hello world" } }
}

• model_config_id is a UUID. The hf-… string you may see elsewhere is the model_name, not the id.
• endpoint_id is the UUID you call for inference (see Inference API).

Python SDK (task_type is required; the result is a dataclass):

reg = client.models.hf.register(
    repo_id="sentence-transformers/all-MiniLM-L6-v2",
    task_type="embeddings",
    lifecycle_status="candidate",
)
print(reg.model_config_id, reg.endpoint_id)

---

Model Registry

List registry

GET /models/registry

Lists models in the registry — both native hive (curated base) models and HuggingFace-registered ones.

Query params:

• source (optional): hive | huggingface
• lifecycle_status (optional): candidate | ready | preferred | disabled
• task_type (optional)
• limit (default 50, max 100), offset (default 0) — offset pagination

Response: { "models": [ ... ] }

curl "https://api.colabhive.com/api/builder/v1/models/registry?source=huggingface&lifecycle_status=ready" \
  -H "X-API-Key: hive_..."

Python SDK (uses offset pagination):

models = client.models.hf.list_registry(source="huggingface", lifecycle_status="ready", limit=50, offset=0)

---

Update lifecycle

PATCH /models/registry/{model_config_id}/lifecycle

Promotes or retires a registered model.

Lifecycle values: candidate | ready | preferred | disabled. Setting disabled requires a reason.

Request:

{ "lifecycle_status": "ready" }

{ "lifecycle_status": "disabled", "reason": "superseded by v2" }

Python SDK:

client.models.hf.update_lifecycle("MODEL_CONFIG_UUID", lifecycle_status="ready")

---

Trained Models

These endpoints manage models produced by your training runs and merges. Model identity is the version_id; the name is a mutable label, so lineage survives renames.

Create model

POST /models

Registers an empty model container — the parent record that trained/merged versions attach to. Most of the time you don't call this directly: a training run, a merge, or a HuggingFace import creates the model and its first version for you. Use it only to pre-create a named container ahead of attaching versions.

Query params (all required):

• account_id — the owning account (must match your key).
• model_name — the model's display name.
• model_architecture — the architecture identifier (e.g. xgboost, qwen2).

cURL:

curl -X POST "https://api.colabhive.com/api/builder/v1/models?account_id=YOUR_ACCOUNT_ID&model_name=my-model&model_architecture=xgboost" \
  -H "X-API-Key: YOUR_API_KEY"

Returns 201 with the created model record.

List models

GET /models

Lists your trained-model artifacts. Cursor pagination (limit, cursor).

for m in client.models.list():
    print(m.model_id, m.framework)

Get model

GET /models/{model_id}

List model versions

GET /models/{model_id}/versions

Each version carries its lineage metadata: framework, precision, base_model_version_id, and training_job_id. Cursor pagination.

Model lineage

GET /models/{model_id}/lineage

Returns the base→derivatives graph (see Merge & Retrain → Model lineage for the full field notes). Nodes you cannot see are returned with "restricted": true — only version_id and edges, no metadata — so the shape of the chain stays visible without leaking detail.

Rename a model version

PATCH /models/{model_id}/versions/{version_id}

Renames a version. The name is a mutable label; renaming never changes the version's identity or its lineage. Owner only. See Merge & Retrain → Rename.

{ "name": "qwen-domain-base-approved" }

Download model

path = client.models.download(model_id="MODEL_ID", output_path="./model.pkl")

Delete model

DELETE /models/{model_id}

---

System Capabilities

GET /capabilities

Returns the capability types the platform can serve.

Response:

{
  "capabilities": [
    "chat.completions",
    "text.completions",
    "text.embeddings",
    "tabular.predict",
    "tabular.classify",
    "image.generate",
    "image.classify",
    "audio.transcribe",
    "audio.generate",
    "rerank"
  ],
  "count": 10
}

---

See Also

• Training API — train your own models
• Merge & Retrain API — merge, retrain-on-top, lineage, rename
• Inference API — run predictions
• OpenAI-Compatible API — POST /v1/chat/completions
• Model Catalog — the live catalog of available models