Skip to main content

Documentation Index

Fetch the complete documentation index at: https://hubify.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​
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

RoleDescriptionTypical Models
orchestratorTop-level agent. Receives Captain instructions, breaks into tasks, manages leads. One per lab.Claude Opus 4.7, GPT-5.4
leadDomain owner. Plans and executes within a domain. Takes over from failed workers.Claude Opus 4.7, Claude Sonnet 4.6, GPT-5.4
workerExecutes specific, scoped tasks dispatched by a lead.Claude Haiku 4.5, GPT-5.4 Mini, Gemini 3.1 Flash

​
Agent Status

StatusDescription
activeOnline and available to receive tasks
idleOnline but not currently working on a task
busyActively executing a task
retiredDeactivated. 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-7, claude-sonnet-4-6, claude-haiku-4-5, gpt-5.4, 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-7",
    "reportsTo": "k68b9l0n3o4p5q6s",
    "capabilities": ["code", "data-analysis", "figures"]
  }'
​
data
object

​
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"

​
Get an Agent

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

​
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-7",
    "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"

​
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}'

​
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"

​
Message Routing

When you send a message to the orchestrator, it routes the request through the agent hierarchy based on reasoning level.
Reasoning LevelRouted ToExamples
HighLeads (Opus-class)Strategy, peer review, paper writing, novel analysis
MediumLeads or workers (Sonnet-class)Code generation, data analysis, experiment design
LowWorkers (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"}
  }'

​
Agent Metrics

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