Actions API

The Actions API provides a plugin-ready surface for discovering and invoking ColabHive models. Designed for workflow tools (n8n, Zapier, Make), AI agents (MCP, LangChain), and custom integrations.

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

---

Concepts

What is an Action?

An Action is any invocable capability on ColabHive — a unified view over LLMs, specialists, tools, and trained models. Each action has:

• A slug (human-readable name, e.g., qwen-2.5-7b-instruct-public)
• A kind (llm, specialist, tool, trained_model, generative, model)
• An input schema (auto-generated from training data when not explicitly set)
• An invoke URL for execution

What is an Invocation?

An Invocation is a single execution of an action. It returns a result (sync) or an invocation_id for polling (async).

Action Kinds

Kind	Description	Examples
llm	Large language models (chat, text generation)	Qwen 7B, Mistral 7B, Phi-3.5
specialist	Task-specific ML endpoints	Embeddings, OCR, STT, Rerank, Translation
tool	Network-enabled utilities	web.fetch, web.search, geo.geocode
trained_model	User-trained models with lineage	BERT classifiers, XGBoost regressors
generative	Content generation models	FLUX / SDXL (images), MusicGen (audio), Wan2.2 (video)
model	Other ML models (tabular, time series)	Prophet, PatchTST, ARIMA

---

Authentication

All Actions API requests require:

X-API-Key: hive_...            # API key (required)
X-Account-ID: <uuid>           # Optional; must match the API key's account when supplied
Content-Type: application/json  # For POST requests

Visibility Rules

• You see your own actions (trained models, registered endpoints)
• You see public approved actions (base models, public endpoints)
• You cannot see other accounts' private actions

---

Discover Actions

List All Actions

GET /actions

Query params:

• kind (optional): llm | specialist | tool | trained_model | generative | model
• task_type (optional): chat | classification | regression | forecasting | embeddings | text-to-image | etc.
• search (optional): Free-text search on slug, display name, or description
• base_only (optional): true = only base models, false = only trained
• limit (optional, default 50, max 200)
• offset (optional, default 0)

cURL:

# List all LLMs
curl "https://api.colabhive.com/api/builder/v1/actions?kind=llm" \
  -H "X-API-Key: $KEY" -H "X-Account-ID: $ACCT"

# List all tools
curl "https://api.colabhive.com/api/builder/v1/actions?kind=tool" \
  -H "X-API-Key: $KEY"

# Search for fraud-related models
curl "https://api.colabhive.com/api/builder/v1/actions?search=fraud&kind=trained_model" \
  -H "X-API-Key: $KEY"

Response:

{
  "actions": [
    {
      "slug": "qwen-2.5-7b-instruct-public",
      "display_name": "Qwen 2.5 7B Instruct",
      "description": "Multilingual chat model",
      "kind": "llm",
      "base_model": "qwen-2.5-7b-instruct",
      "model_category": "nlp",
      "task_type": "chat",
      "source": "hive",
      "input_schema": {
        "type": "object",
        "properties": {
          "messages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "role": {"type": "string", "enum": ["system", "user", "assistant"]},
                "content": {"type": "string"}
              },
              "required": ["role", "content"]
            }
          }
        },
        "required": ["messages"]
      },
      "output_schema": { ... },
      "capabilities": ["chat.completions"],
      "is_base_model": true,
      "invoke_url": "/api/builder/v1/actions/qwen-2.5-7b-instruct-public:invoke"
    }
  ],
  "total": 17,
  "limit": 50,
  "offset": 0
}

Python SDK:

import httpx

BASE = "https://api.colabhive.com/api/builder/v1"
HEADERS = {"X-API-Key": KEY, "X-Account-ID": ACCT}

# Discover all LLMs
actions = httpx.get(f"{BASE}/actions?kind=llm", headers=HEADERS).json()
for action in actions["actions"]:
    print(f"{action['slug']} — {action['task_type']}")

---

Get Action Detail

GET /actions/{slug}

Returns full detail for a single action, including training lineage for trained models.

cURL:

curl "https://api.colabhive.com/api/builder/v1/actions/bert-products-v1" \
  -H "X-API-Key: $KEY"

Response (trained model):

{
  "slug": "bert-products-v1",
  "display_name": "bert-products-v1",
  "description": "BERT classifier for product categories",
  "kind": "trained_model",
  "base_model": "bert-classification-gpu",
  "model_category": "deep_learning",
  "task_type": "classification",
  "source": "hive",
  "input_schema": {
    "type": "object",
    "properties": {
      "features": {
        "type": "object",
        "properties": {"text": {"type": "string"}},
        "required": ["text"]
      }
    },
    "required": ["features"]
  },
  "is_base_model": false,
  "vram_required_mb": 1024,
  "training": {
    "job_id": "uuid",
    "dataset": "products-catalog",
    "dataset_domain": "text",
    "architecture": "bert-classification-gpu (transformers)",
    "columns": {
      "text_column": "text",
      "label_column": "category"
    }
  },
  "invoke_url": "/api/builder/v1/actions/bert-products-v1:invoke"
}

---

Invoke Actions

Execute an Action

POST /actions/{slug}:invoke

Request:

{
  "input": { ... },
  "sync": true,
  "sync_timeout_s": 30
}

Input format depends on the action kind:

Kind	Input Format	Example
llm	{"messages": [{"role": "user", "content": "..."}]}	Chat completion
specialist (embeddings)	{"text": "..."}	Text embedding
specialist (rerank)	{"query": "...", "documents": ["..."]}	Reranking
tool	{"url": "..."} or {"query": "..."}	Web fetch/search
trained_model (tabular)	{"features": {"col1": 1.0, "col2": "val"}}	Prediction
trained_model (NLP)	{"features": {"text": "..."}}	Classification
trained_model (time series)	{"values": [1.2, 3.4, ...], "horizon": 10}	Forecasting
generative	{"prompt": "...", "width": 1024}	Image generation

cURL examples:

# Invoke an LLM
curl -X POST "https://api.colabhive.com/api/builder/v1/actions/qwen-2.5-7b-instruct-public:invoke" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"input": {"messages": [{"role": "user", "content": "Hello!"}]}}'

# Invoke embeddings
curl -X POST "https://api.colabhive.com/api/builder/v1/actions/embeddings-public:invoke" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"input": {"text": "semantic search query"}}'

# Invoke a trained model (async)
curl -X POST "https://api.colabhive.com/api/builder/v1/actions/my-fraud-detector:invoke" \
  -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
  -d '{"input": {"features": {"amount": 1500, "merchant": "electronics"}}, "sync": false}'

Response (sync — completed):

{
  "invocation_id": "uuid",
  "action_slug": "qwen-2.5-7b-instruct-public",
  "status": "succeeded",
  "model_state": "resident",
  "inference_time_ms": 245.5,
  "result": { ... },
  "sync_latency_ms": 230,
  "message": "Invocation completed"
}

Response (async — queued):

{
  "invocation_id": "uuid",
  "action_slug": "my-fraud-detector",
  "status": "queued",
  "model_state": "cold",
  "estimated_load_time_s": 30,
  "message": "Invocation queued",
  "poll_url": "/api/builder/v1/invocations/uuid"
}

---

Poll Invocation Status

Get Invocation

GET /invocations/{invocation_id}

Poll this endpoint after an async invocation until status is succeeded or failed.

cURL:

curl "https://api.colabhive.com/api/builder/v1/invocations/{INVOCATION_ID}" \
  -H "X-API-Key: $KEY"

Response (completed):

{
  "invocation_id": "uuid",
  "status": "succeeded",
  "result": {"prediction": "electronics", "confidence": 0.94},
  "error": null,
  "metrics": { ... },
  "created_at": "2026-04-08T15:33:49Z",
  "completed_at": "2026-04-08T15:33:52Z"
}

Response (in progress):

{
  "invocation_id": "uuid",
  "status": "running",
  "status_detail": {
    "status": "loading_model",
    "progress_pct": 75,
    "substatus": "loading_weights"
  },
  "result": null,
  "created_at": "2026-04-08T15:33:49Z"
}

Status values: queued | assigned | preparing | downloading_model | loading_model | running | succeeded | failed

---

End-to-End Examples

Python: Discover and invoke the best LLM

import httpx, time

BASE = "https://api.colabhive.com/api/builder/v1"
HEADERS = {"X-API-Key": KEY, "Content-Type": "application/json"}

# 1. Discover available LLMs
actions = httpx.get(f"{BASE}/actions?kind=llm", headers=HEADERS).json()
llm = actions["actions"][0]  # Pick first available
print(f"Using: {llm['slug']}")

# 2. Invoke it
resp = httpx.post(
    f"{BASE}/actions/{llm['slug']}:invoke",
    headers=HEADERS,
    json={"input": {"messages": [{"role": "user", "content": "What is 2+2?"}]}}
).json()

# 3. Handle sync vs async
if resp["status"] == "succeeded":
    print(resp["result"])
else:
    # Poll
    while True:
        status = httpx.get(f"{BASE}/invocations/{resp['invocation_id']}", headers=HEADERS).json()
        if status["status"] in ("succeeded", "failed"):
            print(status["result"] or status["error"])
            break
        time.sleep(2)

JavaScript: Invoke embeddings

const resp = await fetch(
  `https://api.colabhive.com/api/builder/v1/actions/embeddings-public:invoke`,
  {
    method: 'POST',
    headers: { 'X-API-Key': KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ input: { text: "hello world" } }),
  }
);
const { invocation_id, status, result } = await resp.json();

---

See Also

• Inference API — endpoint-based inference (by UUID)
• Agent Integration — readiness-aware routing
• Model Catalog — all available models
• Authentication — API key setup