Agents

Manage agents over the API — create and edit them, move a draft through its version lifecycle, attach data and tools, and export or import an agent as a package. To talk to an agent, see Conversations.

All paths are relative to the base URL and require an Authorization: Bearer YOUR_API_KEY header.

The agent object

PublicAgent is returned by most endpoints here.

Field	Type	Description
id	string	Agent ID.
name	string	Agent name.
description	string	What the agent does.
runbook_text	string	Raw text of the agent's runbook.
state	string	Lifecycle state — `draft` or `live` (lowercase).
version	string	Current version label.
live_version_id	string	ID of the published live version, if any.
architecture_name	string	The agent's architecture.
architecture_version	string	Architecture version.
created_by	string	User who created the agent.
created_at / updated_at	string	Timestamps.

List agents

GET /agents

Parameter	In	Type	Required	Description
name	query	string	No	Filter by name (starts-with, case-insensitive).
limit	query	integer	No	Page size.
next	query	string	No	Pagination token.

Returns a PaginatedResponse whose data is a list of agents.

Get agent

GET /agents/{agent_id}

Returns a single PublicAgent.

Create agent

POST /agents

Creates a new agent owned by the authenticated key.

Body

Field	Type	Required	Description
name	string	Yes	Agent name.
description	string	No	What the agent does.
runbook_text	string	No	The agent's runbook, as Markdown text.
architecture_name	string	No	Architecture to use (defaults applied).
architecture_version	string	No	Architecture version.

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Invoice Roast",
    "description": "Forensic expense analyst.",
    "runbook_text": "## Objective\nExtract and check receipts."
  }'

Returns the created PublicAgent.

Update agent

PATCH /agents/{agent_id}

Partially updates an agent; absent fields are left untouched.

Body

Field	Type	Required	Description
name	string	No	New name.
description	string	No	New description.
runbook_text	string	No	New runbook text.

You can't patch a live agent directly. Enter edit mode first (POST /agents/{agent_id}/edit), make your changes against the draft, then publish.

Delete agent

DELETE /agents/{agent_id}

Deletes an agent (requires ownership). Returns 204 No Content.

Version lifecycle

An agent has a published live version that users see, and a draft you edit — see the Versioning & lifecycle concept. These endpoints drive that flow.

The lifecycle endpoints require the agent lifecycle capability to be enabled on the deployment.

Enter edit mode

POST /agents/{agent_id}/edit

Flips the agent to draft so you can iterate. Idempotent — a draft stays a draft. Returns the PublicAgent.

Publish

POST /agents/{agent_id}/publish

Snapshots the current draft as a new version, flips the agent to live, and points live_version_id at it. Requires draft state.

Body

Field	Type	Required	Description
description	string	No	Change description for this publish.
connection_mappings	object<string>	No	Map test data-connection IDs → prod data-connection IDs.
mcp_server_mappings	object<string>	No	Map test MCP server IDs → prod MCP server IDs.

The mappings let you swap the draft's test resources for production equivalents at publish time. Returns the PublicAgent.

Discard draft

POST /agents/{agent_id}/discard-draft

Reverts the agent's content to the live version. Requires a prior publish (a live_version_id must exist). Takes the same connection_mappings / mcp_server_mappings body as publish. Returns the PublicAgent.

Get lifecycle state

GET /agents/{agent_id}/state

{ "state": "draft", "live_version_id": "string", "has_draft": true }

Field	Type	Description
state	string	`draft` or `live` (lowercase).
live_version_id	string	ID of the published live version, if any.
has_draft	boolean	Whether an editable draft exists.

Attached data & tools

Attaching or detaching requires ownership of the agent — attaching to an agent you don't own returns 403.

MCP servers

GET /agents/{agent_id}/mcp-servers — list the MCP servers attached to the agent (paginated).
POST /agents/{agent_id}/mcp-servers — attach one. Body: { "mcp_server_id": "..." }. Returns 204.
DELETE /agents/{agent_id}/mcp-servers/{mcp_server_id} — detach one.

Semantic data models

GET /agents/{agent_id}/semantic-data-models — list the SDMs attached to the agent (paginated).
POST /agents/{agent_id}/semantic-data-models — attach one. Body: { "semantic_data_model_id": "..." }. Returns 204.
DELETE /agents/{agent_id}/semantic-data-models/{semantic_data_model_id} — detach one.

Export & import

Export

GET /agents/{agent_id}/export

Streams the agent — with its SDMs, MCP servers, action packages, and shared files — as a zip package.

Import

POST /agents/import

Creates a new agent from a previously exported zip. Send as multipart/form-data with a file field carrying the zip.

curl -X POST 'https://{your-deployment-host}/tenants/{tenant-id}/api/v2/agents/import' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@agent-package.zip'

Returns the created PublicAgent.

REST API Conversations