Admin REST API

Use the local admin server before following these requests. Set ADMIN_TOKEN in this terminal to match the server. The examples use its deterministic fixture provider; configuration operations and the shown run make no model calls. createAdminRouter() creates and updates Agents and Teams. Workflow routes only store name/description metadata; they do not accept steps or create executable Workflows. Every route is part of your trusted operator API. The host must authenticate it separately from application transport.

Endpoints

Agents

Method	Path	Description
POST	`/agents`	Create agent from blueprint
GET	`/agents`	List all persisted agent configs
GET	`/agents/:name`	Get single agent config
PUT	`/agents/:name`	Update agent (destroy + recreate)
DELETE	`/agents/:name`	Remove from registry + storage

Teams

Method	Path	Description
POST	`/teams`	Create team from agent names
GET	`/teams`	List all persisted team configs
GET	`/teams/:name`	Get single team config
PUT	`/teams/:name`	Update team
DELETE	`/teams/:name`	Remove from registry + storage

Workflows

Method	Path	Description
POST	`/workflows`	Register workflow metadata
GET	`/workflows`	List persisted workflow configs
GET	`/workflows/:name`	Get single workflow config
DELETE	`/workflows/:name`	Remove from registry + storage

Tools

Method	Path	Description
GET	`/tools`	List all available tools (static + dynamic toolkit configs)
GET	`/tools/:name`	Get single tool detail (name, description, parameters)

Toolkit Catalog

Method	Path	Description
GET	`/toolkit-catalog`	List all available toolkit types with config requirements
GET	`/toolkit-catalog/:id`	Get single toolkit type detail

Toolkit Configs (Credentials Management)

Method	Path	Description
POST	`/toolkit-configs`	Save toolkit config (credentials + settings)
GET	`/toolkit-configs`	List all saved configs (secrets masked)
GET	`/toolkit-configs/:name`	Get single config (secrets masked)
PUT	`/toolkit-configs/:name`	Update config (secrets preserved if masked values sent)
DELETE	`/toolkit-configs/:name`	Remove config and deactivate toolkit

Create Agent

curl -X POST http://127.0.0.1:3000/admin/agents \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "researcher",
    "provider": "fixture",
    "model": "local-v1",
    "instructions": "You research topics thoroughly.",
    "tools": []
  }'

{
  "name": "researcher",
  "provider": "fixture",
  "model": "local-v1",
  "instructions": "You research topics thoroughly.",
  "tools": [],
  "createdAt": "2026-10-04T10:00:00.000Z",
  "updatedAt": "2026-10-04T10:00:00.000Z"
}

The Agent is immediately available through the overview server’s transport, which discovers registered entities. Its fixture response is fixed regardless of the prompt:

curl -X POST http://127.0.0.1:3000/api/agents/researcher/run \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"input": "What is quantum computing?"}'

Agent Blueprint

string

required

Unique agent name. Used as the identifier in registry and transport routes.

string

required

Model provider id: "openai", "anthropic", "google", "ollama", "vertex".

string

required

Model ID accepted by the selected provider. This walkthrough uses "local-v1"; choose a live provider/model from example models when adapting it.

string

System prompt for the agent.

string[]

Tool names from the toolLibrary. e.g., ["webSearch", "calculator"].

number

Optional sampling value. Supported ranges and compatibility depend on the provider/model.

object

Provider-specific configuration passed to modelRegistry.resolve(). It is persisted privately and omitted from public responses; prefer host environment credentials where supported.

Update Agent

curl -X PUT http://127.0.0.1:3000/admin/agents/researcher \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"model": "local-v2", "instructions": "Be concise."}'

The registry entry is replaced with a newly configured Agent and the blueprint is persisted. This does not cancel or drain runs already using the old instance; coordinate operator changes with the host lifecycle.

Create Team

First create writer with the Agent request above and "name": "writer". Then submit the Team with both existing member names:

curl -X POST http://127.0.0.1:3000/admin/teams \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "content-team",
    "mode": "coordinate",
    "provider": "fixture",
    "model": "local-v1",
    "members": ["researcher", "writer"]
  }'

All member Agents must already exist in the registry. Before the Team request, create writer using the same Agent request with "name": "writer". The local fixture demonstrates configuration wiring; it does not perform useful model coordination. Use real providers when testing Team behavior.

Team Blueprint

string

required

Unique team name.

string

required

Team mode: "coordinate", "route", "broadcast", "collaborate", "handoff".

string

required

Model provider for the team leader.

string

required

Model id for the team leader.

string[]

required

Agent names that must exist in the registry.

string

System prompt for the team leader.

Validation & Error Codes

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

Workflow metadata

A POST /workflows body accepts name and optional description. There is no workflow-update route or serialized step graph. To execute a Workflow, define its steps in application code and register it with core. Deleting metadata also removes a matching live registry entry, if one exists.

Toolkit configuration

Browse /toolkit-catalog for registered toolkit types and configuration fields. Save an instance with toolkitId, instanceName, config, and optional enabled. Enabling it exposes its tools to subsequent Agent creation; inspect /tools for the exact names before adding them to a blueprint. Toolkit response masking follows catalog fields marked secret. Masked placeholder values on update preserve those existing secret values. Storage retains the original settings; see storage ownership and sensitive values.

Verify an integration

Check missing credentials, unknown tool names, duplicate entity names, and restart hydration before connecting an operator UI. Distinguish /admin/agents (persisted blueprints) from the transport registry (currently executable instances). Continue with Socket.IO for configuration-change notifications.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Endpoints

Agents

Teams

Workflows

Tools

Toolkit Catalog

Toolkit Configs (Credentials Management)

Create Agent

Agent Blueprint

Update Agent

Create Team

Team Blueprint

Validation & Error Codes

Workflow metadata

Toolkit configuration

Verify an integration

​Endpoints

​Agents

​Teams

​Workflows

​Tools

​Toolkit Catalog

​Toolkit Configs (Credentials Management)

​Create Agent

​Agent Blueprint

​Update Agent

​Create Team

​Team Blueprint

​Validation & Error Codes

​Workflow metadata

​Toolkit configuration

​Verify an integration

Endpoints

Agents

Teams

Workflows

Tools

Toolkit Catalog

Toolkit Configs (Credentials Management)

Create Agent

Agent Blueprint

Update Agent

Create Team

Team Blueprint

Validation & Error Codes

Workflow metadata

Toolkit configuration

Verify an integration