Agents API

Today only GET /v1/agents (list agents in a lab) is shipped. The per-agent sub-routes described below (GET /v1/agents/{id}, /messages, /metrics, /start, /stop) are planned, not yet live. Drive individual agents from the web app or via Convex actions; this page documents the target REST shape so SDKs can build against it.

Every lab runs a hierarchical multi-agent system: an orchestrator directs lead agents who dispatch workers. The Agents API lets you configure the roster, start/stop agents, query status, and route messages.

Agent Roles

Role	Description	Typical Models
`orchestrator`	Top-level agent. Receives Captain instructions, breaks into tasks, manages leads. One per lab.	Claude Opus 4.8, GPT-5.5
`lead`	Domain owner. Plans and executes within a domain. Takes over from failed workers.	Claude Opus 4.8, Claude Sonnet 5, GPT-5.5
`worker`	Executes specific, scoped tasks dispatched by a lead.	Claude Haiku 4.5, GPT-5.5 Mini, Gemini 3.1 Flash

Agent Status

Status	Description
`active`	Online and available to receive tasks
`idle`	Online but not currently working on a task
`busy`	Actively executing a task
`retired`	Deactivated. Will not receive tasks.

Create an Agent

labId

string

required

Lab this agent belongs to.

name

string

required

Display name (e.g., “Research Lead”, “Figure Worker”).

role

string

required

Agent role: orchestrator, lead, or worker.

model

string

required

Model identifier (e.g., claude-opus-4-8, claude-sonnet-5, claude-haiku-4-5, gpt-5.5, gemini-3.1-pro, grok-4, sonar-pro).

reportsTo

string

Convex ID of the agent this one reports to. Workers report to leads; leads report to the orchestrator.

systemPrompt

string

Custom system prompt. Overrides the default for this role.

capabilities

string[]

List of capabilities (e.g., ["code", "figures", "latex", "data-analysis"]).

curl -X POST https://www.hubify.com/api/v1/agents \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "labId": "j57a8k9m2n3p4q5r",
    "name": "Research Lead",
    "role": "lead",
    "model": "claude-opus-4-8",
    "reportsTo": "k68b9l0n3o4p5q6s",
    "capabilities": ["code", "data-analysis", "figures"]
  }'

const agent = await hubify.agents.create({
  labId: "j57a8k9m2n3p4q5r",
  name: "Research Lead",
  role: "lead",
  model: "claude-opus-4-8",
  reportsTo: "k68b9l0n3o4p5q6s",
  capabilities: ["code", "data-analysis", "figures"],
});

data

object

Show Agent object

_id

string

required

Convex document ID.

labId

string

required

Parent lab ID.

name

string

required

Display name.

role

string

required

Agent role.

model

string

required

Model identifier.

status

string

required

Current status.

reportsTo

string

ID of the supervising agent.

parentAgentId

string

ID of the agent that delegated the current task.

currentTaskDescription

string

What the agent is currently working on.

systemPrompt

string

Custom system prompt.

capabilities

string[]

Agent capabilities.

totalTasks

number

required

Lifetime tasks completed.

totalTokens

number

required

Lifetime tokens consumed.

createdAt

number

required

Creation timestamp (ms).

List Agents

labId

string

required

Lab ID to list agents for.

role

string

Filter by role: orchestrator, lead, worker.

status

string

Filter by status: active, idle, busy, retired.

curl "https://www.hubify.com/api/v1/agents?labId=j57a8k9m2n3p4q5r&role=lead" \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const leads = await hubify.agents.list({
  labId: "j57a8k9m2n3p4q5r",
  role: "lead",
});

Get an Agent

curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const agent = await hubify.agents.get({ agentId: "k68b9l0n3o4p5q6s" });

Update an Agent

name

string

Updated display name.

model

string

Change the model (e.g., upgrade from Sonnet to Opus).

systemPrompt

string

Updated system prompt.

capabilities

string[]

Updated capabilities list.

reportsTo

string

Change the supervising agent.

curl -X PATCH https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "claude-opus-4-8",
    "capabilities": ["code", "data-analysis", "figures", "latex"]
  }'

await hubify.agents.update({
  agentId: "k68b9l0n3o4p5q6s",
  model: "claude-opus-4-8",
  capabilities: ["code", "data-analysis", "figures", "latex"],
});

Start an Agent

Activate a retired or newly created agent so it begins receiving tasks.

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/start \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.agents.start({ agentId: "k68b9l0n3o4p5q6s" });

Stop an Agent

Set an agent to retired status. It finishes any in-progress task, then stops accepting new work.

force

boolean

default:false

If true, immediately stop the agent and reassign its current task.

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/stop \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"force": false}'

await hubify.agents.stop({ agentId: "k68b9l0n3o4p5q6s", force: false });

Delete an Agent

Remove an agent from the lab. The agent must be in retired status.

curl -X DELETE https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

await hubify.agents.delete({ agentId: "k68b9l0n3o4p5q6s" });

Message Routing

When you send a message to the orchestrator, it routes the request through the agent hierarchy based on reasoning level.

Reasoning Level	Routed To	Examples
High	Leads (Opus-class)	Strategy, peer review, paper writing, novel analysis
Medium	Leads or workers (Sonnet-class)	Code generation, data analysis, experiment design
Low	Workers (Haiku-class)	Formatting, data ingestion, wiki updates, figure export

Send a Message to an Agent

agentId

string

required

Target agent ID. Use the orchestrator ID for automatic routing.

content

string

required

Message content.

context

object

Optional context (e.g., which experiment or paper is being discussed).

curl -X POST https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/messages \
  -H "Authorization: Bearer $HUBIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Run a Fisher forecast for f_NL with the DESI DR1 tracer sample",
    "context": {"experimentId": "EXP-054"}
  }'

await hubify.agents.sendMessage({
  agentId: "k68b9l0n3o4p5q6s",
  content: "Run a Fisher forecast for f_NL with the DESI DR1 tracer sample",
  context: { experimentId: "EXP-054" },
});

Agent Metrics

curl https://www.hubify.com/api/v1/agents/k68b9l0n3o4p5q6s/metrics \
  -H "Authorization: Bearer $HUBIFY_TOKEN"

const metrics = await hubify.agents.getMetrics({
  agentId: "k68b9l0n3o4p5q6s",
});

data

object

Show Agent metrics

totalTasks

number

Lifetime tasks completed.

totalTokens

number

Lifetime tokens consumed.

averageTaskDuration

number

Average task duration in seconds.

successRate

number

Percentage of tasks completed without error (0-1).

costUsd

number

Total LLM cost in USD.

Overview

Labs

Data

Compute

Lab Ops

Agents

Agents API

Agent Roles

Agent Status

Create an Agent

List Agents

Get an Agent

Update an Agent

Start an Agent

Stop an Agent

Delete an Agent

Message Routing

Send a Message to an Agent

Agent Metrics

​Agents API

​Agent Roles

​Agent Status

​Create an Agent

​List Agents

​Get an Agent

​Update an Agent

​Start an Agent

​Stop an Agent

​Delete an Agent

​Message Routing

​Send a Message to an Agent

​Agent Metrics

Agents API

Agent Roles

Agent Status

Create an Agent

List Agents

Get an Agent

Update an Agent

Start an Agent

Stop an Agent

Delete an Agent

Message Routing

Send a Message to an Agent

Agent Metrics