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.

Each model item backed by Hugging Face exposes hf_repo_id, hf_revision, license_id, license_class, requires_end_user_acceptance, attribution_required, redistribution_allowed, license_source_url, and license_verified_at. See the revision-pinned license catalog before invoking a third-party model.

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}

Scorer models (CLM)

The catalog row clm-v0.1-8b is a scorer, not a language model: its hf_repo_id is Qwen/Qwen3-8B because that is its encoder, but it serves CLM-8B — typed questions and ranking, no text generation. It is reached through its endpoint (task_type clm), by POST /v1/systemone and POST /v1/rank or by POST /endpoints/{id}/infer, never by chat completions. Importing Qwen/Qwen3-8B through POST /models/hf/register gives you the chat LLM, not the scorer.

Heads trained with the clm-head-infonce template are model versions like any other trained model; registering the run for inference gives the head its own endpoint, served by the clm-v0.1-8b replicas. See Fine-tune a CLM head.

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
}

HuggingFace Model Discovery​

Search HuggingFace models​

Get HuggingFace model info​

Register a HuggingFace model​

Model Registry​

List registry​

Update lifecycle​

Trained Models​

Create model​

List models​

Get model​

List model versions​

Model lineage​

Rename a model version​

Download model​

Delete model​

Scorer models (CLM)​

System Capabilities​

See Also​

HuggingFace Model Discovery

Search HuggingFace models

Get HuggingFace model info

Register a HuggingFace model

Model Registry

List registry

Update lifecycle

Trained Models

Create model

List models

Get model

List model versions

Model lineage

Rename a model version

Download model

Delete model

Scorer models (CLM)

System Capabilities

See Also