Skip to main content

​
Admin REST API

The createAdminRouter() function returns an Express router with full CRUD endpoints for agents, teams, and workflows.

​
Endpoints

​
Agents

MethodPathDescription
POST/agentsCreate agent from blueprint
GET/agentsList all persisted agent configs
GET/agents/:nameGet single agent config
PUT/agents/:nameUpdate agent (destroy + recreate)
DELETE/agents/:nameRemove from registry + storage

​
Teams

MethodPathDescription
POST/teamsCreate team from agent names
GET/teamsList all persisted team configs
GET/teams/:nameGet single team config
PUT/teams/:nameUpdate team
DELETE/teams/:nameRemove from registry + storage

​
Workflows

MethodPathDescription
POST/workflowsRegister workflow metadata
GET/workflowsList persisted workflow configs
GET/workflows/:nameGet single workflow config
DELETE/workflows/:nameRemove from registry + storage

​
Tools

MethodPathDescription
GET/toolsList all available tools (static + dynamic toolkit configs)
GET/tools/:nameGet single tool detail (name, description, parameters)

​
Toolkit Catalog

MethodPathDescription
GET/toolkit-catalogList all available toolkit types with config requirements
GET/toolkit-catalog/:idGet single toolkit type detail

​
Toolkit Configs (Credentials Management)

MethodPathDescription
POST/toolkit-configsSave toolkit config (credentials + settings)
GET/toolkit-configsList all saved configs (secrets masked)
GET/toolkit-configs/:nameGet single config (secrets masked)
PUT/toolkit-configs/:nameUpdate config (secrets preserved if masked values sent)
DELETE/toolkit-configs/:nameRemove config and deactivate toolkit

​
Create Agent

curl -X POST http://localhost:3000/admin/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "provider": "openai",
    "model": "gpt-4o",
    "instructions": "You research topics thoroughly.",
    "tools": ["webSearch"]
  }'

{
  "name": "researcher",
  "provider": "openai",
  "model": "gpt-4o",
  "instructions": "You research topics thoroughly.",
  "tools": ["webSearch"],
  "createdAt": "2026-02-27T10:00:00.000Z",
  "updatedAt": "2026-02-27T10:00:00.000Z"
}
The agent is immediately available via the transport layer: 
curl -X POST http://localhost:3000/api/agents/researcher/run \
  -H "Content-Type: application/json" \
  -d '{"input": "What is quantum computing?"}'

​
Agent Blueprint

​
name
string
required
Unique agent name. Used as the identifier in registry and transport routes.
​
provider
string
required
Model provider id: "openai", "anthropic", "google", "ollama", "vertex".
​
model
string
required
Model id: "gpt-4o", "gpt-4o-mini", "claude-sonnet-4-20250514", etc.
​
instructions
string
System prompt for the agent.
​
tools
string[]
Tool names from the toolLibrary. e.g., ["webSearch", "calculator"].
​
temperature
number
Model temperature (0-2).
​
providerConfig
object
Provider-specific config passed to modelRegistry.resolve() (e.g., { apiKey, baseURL }).

​
Update Agent

curl -X PUT http://localhost:3000/admin/agents/researcher \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "instructions": "Be concise."}'
The old agent is removed from the registry, a new one is created with the updated config, and the blueprint is persisted.

​
Create Team

curl -X POST http://localhost:3000/admin/teams \
  -H "Content-Type: application/json" \
  -d '{
    "name": "content-team",
    "mode": "coordinate",
    "provider": "openai",
    "model": "gpt-4o",
    "members": ["researcher", "writer"]
  }'
All member agents must already exist in the registry.

​
Team Blueprint

​
name
string
required
Unique team name.
​
mode
string
required
Team mode: "coordinate", "route", "broadcast", "collaborate", "handoff".
​
provider
string
required
Model provider for the team leader.
​
model
string
required
Model id for the team leader.
​
members
string[]
required
Agent names that must exist in the registry.
​
instructions
string
System prompt for the team leader.

​
Validation & Error Codes

StatusMeaning
201Created successfully
400Missing required fields
404Entity not found
409Name already exists
422Validation error (unknown provider, missing tool, missing member agent)
500Internal error