Agents

Create, manage, and interact with AI agents. Agents are workflow-powered intelligent assistants that run as persistent pods with function-calling capabilities, persistent memory, and tool access.

All endpoints require authentication via X-API-Key header and the appropriate scope.

Agent Object

{
  "_id": "wf_abc123",
  "name": "C-Suite CMO",
  "status": "running",
  "agentId": "pod_xyz789",
  "agentType": "function-calling",
  "toolsCount": 12,
  "memoryTypes": ["conversation", "episodic"],
  "config": {
    "temperature": 0.7,
    "max_iterations": 15
  },
  "liveState": {
    "currentActivity": "idle"
  },
  "createdAt": "2025-01-15T10:30:00Z",
  "lastActivity": "2025-02-01T14:22:00Z"
}

`GET` /api/v1/agents

List all agents accessible to the authenticated user. Returns agent-mode workflows enriched with live pod status.

Scope: agents:read

Query Parameters

Parameter	Type	Required	Description
`q`	string	No	Search by agent name
`status`	string	No	Filter by status: `running`, `stopped`, `starting`
`limit`	integer	No	Number of results to return (default: 50)
`cursor`	string	No	`meta.nextCursor` of the previous page; omit for the first page
`sort`	string	No	Sort field and direction, e.g. `-createdAt`

Response 200 OK

{
  "data": [
    {
      "_id": "wf_abc123",
      "name": "C-Suite CMO",
      "status": "running",
      "agentId": "pod_xyz789",
      "agentType": "function-calling",
      "toolsCount": 12,
      "lastActivity": "2025-02-01T14:22:00Z",
      "createdAt": "2025-01-15T10:30:00Z",
      "knowledgeBaseIds": []
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "nextCursor": null,
    "requestId": "req_abc123"
  }
}

`GET` /api/v1/agents/:id

Get detailed agent information including live status, config, and nodes. attachments lists the workflows the agent calls as tools and the add-ons provisioned for it; each keeps that workflow or add-on in use until it is removed from the agent (below). health is the platform's last check of the running agent's server, made about every 30 seconds: status is healthy, unhealthy, unreachable or error, with the reason in error. It is null until the first check and while the agent is not running.

Scope: agents:read

Response 200 OK

{
  "data": {
    "_id": "wf_abc123",
    "name": "C-Suite CMO",
    "mode": "agent",
    "status": "running",
    "podId": "pod_xyz789",
    "health": {
      "status": "healthy",
      "podStatus": "running",
      "checkedAt": "2025-02-01T14:22:30Z",
      "error": null,
      "replicas": { "desired": 1, "ready": 1, "available": 1 }
    },
    "healthUpdatedAt": "2025-02-01T14:22:30Z",
    "agentType": "function-calling",
    "toolsCount": 12,
    "memoryTypes": ["conversation", "episodic"],
    "config": { "temperature": 0.7 },
    "liveState": { "currentActivity": "idle" },
    "nodes": [...],
    "connections": [...],
    "attachments": {
      "toolWorkflows": [{ "_id": "wf_orders", "name": "Order lookup", "status": "draft" }],
      "addons": [{ "_id": "addon-1a2b", "type": "postgres", "name": "Orders", "status": "running" }]
    },
    "createdAt": "2025-01-15T10:30:00Z",
    "lastActivity": "2025-02-01T14:22:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`DELETE` /api/v1/agents/:id

Delete an agent. Stops the pod if running, removes agent mode from the workflow, and cleans up pod records.

Scope: agents:write

Response 204 No Content

`PATCH` /api/v1/agents/:id

Update the agent's workflow: any of name, description, nodes, connections. Returns the agent.

Scope: agents:write

{ "name": "Iris", "description": "Personal assistant" }

`PATCH` /api/v1/agents/:id/config

Update the agent's brain config: only the keys sent change; it returns the config. Operating-prompt text edits live-reload on the agent's next turn. Every other change requires a redeploy -- call POST /agents/:id/redeploy afterwards (GET /agents/:id/config reports applyPending: true until then).

Scope: agents:write

Request Body -- any subset of:

{
  "personality": "Warm, direct, technically competent. Asks one clarifying question when ambiguous.",
  "operatingPromptId": "prompt_xyz123",
  "contextPolicy": { "kind": "summarise", "tokenBudget": 8000, "keepRecent": 12 },
  "sessionPolicy": {
    "idleTimeoutSeconds": 1800,
    "maxSessionDurationSeconds": 14400,
    "maxConcurrentSessionsPerUser": 3,
    "autoArchiveAfterDays": 30,
    "allowPerSessionModelOverride": false
  },
  "heartbeatEnabled": true,
  "heartbeatCron": "0 9 * * *",
  "heartbeatTimezone": "America/New_York",
  "maxIterations": 15,
  "knowledgeBaseIds": ["kb_abc123"]
}

Also temperature (0 to 2), maxTokens, responseFormat (json_object or text) and builtInTools ({ "disabled": [...] }).

Response 200 OK: the agent's config, as GET /agents/:id/config returns it.

`GET` /api/v1/agents/:id/config

Read the agent's current brain config plus pod state.

Scope: agents:read

Response 200 OK

{
  "data": {
    "agentName": "Iris",
    "agentType": "function-calling",
    "isRunning": true,
    "agentPodId": "pod_abc",
    "config": {
      "heartbeatEnabled": false,
      "heartbeatCron": "0 * * * *",
      "heartbeatTimezone": "UTC",
      "maxIterations": 10,
      "personality": "Warm, direct…",
      "operatingPromptId": "prompt_xyz123",
      "contextPolicy": { "kind": "summarise", "tokenBudget": 8000, "keepRecent": 12 },
      "sessionPolicy": { "idleTimeoutSeconds": 1800, "maxSessionDurationSeconds": 14400, "maxConcurrentSessionsPerUser": 3, "autoArchiveAfterDays": 30, "allowPerSessionModelOverride": false },
      "primaryModelId": "model_anthropic_sonnet",
      "fallbackModelIds": ["model_openai_gpt4o"]
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`PATCH` /api/v1/agents/:id/model

Swap the agent's primary AI model and (optional) ordered fallback list. Triggers a STRONGLY_SERVICES bundle rebuild so the new model id is resolvable at runtime. Call POST /agents/:id/redeploy afterwards to bring up a pod on the new model.

Scope: agents:write

Request Body

{
  "modelId": "model_anthropic_sonnet",
  "fallbackModelIds": ["model_openai_gpt4o", "model_meta_llama70b"]
}

Response 200 OK

{
  "data": {
    "success": true,
    "modelId": "model_anthropic_sonnet",
    "fallbackModelIds": ["model_openai_gpt4o", "model_meta_llama70b"]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`POST` /api/v1/agents/:id/redeploy

Apply pending brain-config changes to a running agent by stopping and re-starting the pod. No-op when the agent is not running.

Scope: agents:write

Response `200 OK`

The agent, as GET /agents/:id shows it. An agent with no running pod is not restarted: its status stays stopped (start it with POST /agents/:id/start).

`POST` /api/v1/agents

One-shot agent creation from Agent Builder wizard input. Auto-provisions required add-ons (e.g. MongoDB for memory), builds the brain workflow with personality + operating prompt + context policy + session policy + model, and seeds Library content (memory / rules / skills / tasks) scoped to the new agent.

Scope: agents:write

Request Body

{
  "name": "Iris",
  "personality": "Warm, direct, technically competent.",
  "operatingPromptId": "prompt_default_op",
  "aiModelId": "model_anthropic_sonnet",
  "fallbackModelIds": ["model_openai_gpt4o"],
  "contextPolicy": { "kind": "summarise", "tokenBudget": 8000, "keepRecent": 12 },
  "sessionPolicy": {
    "idleTimeoutSeconds": 1800,
    "maxSessionDurationSeconds": 14400,
    "maxConcurrentSessionsPerUser": 3,
    "autoArchiveAfterDays": 30,
    "allowPerSessionModelOverride": false
  },
  "connectors": [
    { "tileId": "web-search", "nodeType": "web-search", "label": "Web Search", "category": "code", "config": { "provider": "duckduckgo" } }
  ],
  "training": {
    "memory": [],
    "rules": [{ "description": "Confirm before sending", "content": "…", "category": "must", "severity": "high" }],
    "skills": [],
    "tasks": []
  }
}

All fields except name are optional. contextPolicy.tokenBudget may not exceed the aiModelId model's context window (400 validation-error otherwise; the same rule applies to the config update and model change). When operatingPromptId is omitted the platform default is used. When personality is omitted the platform DEFAULT_PERSONALITY is used.

Response 201 Created

The new agent, status stopped until you start it.

`GET` /api/v1/agents/name-availability

Check whether a given agent name is available for the calling user. Returns available: false with a reason of duplicate or invalid when the name can't be used.

Scope: agents:read

Query Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Candidate name
`ignoreWorkflowId`	string	No	Skip this workflow id when checking (use during rename)

Response 200 OK

{ "data": { "available": false, "reason": "duplicate", "conflictWorkflowId": "wf_other" }, "meta": { "requestId": "req_abc123" } }

`POST` /api/v1/agents/:id/start

Start an agent pod. Creates a persistent Kubernetes pod running the agent server with function-calling capabilities and tool access.

Scope: agents:write

Response `200 OK`

The agent, as GET /agents/:id shows it, with mcpRegisterFailures: the connectors whose tools the started agent is missing. A non-empty list means the agent cannot use those tools: fix or re-provision the connector and start it again. Starting an agent that is already running answers the agent (without mcpRegisterFailures).

{
  "data": {
    "_id": "wf_abc123",
    "name": "Support agent",
    "status": "running",
    "toolsCount": 12,
    "mcpRegisterFailures": []
  },
  "meta": { "requestId": "req_abc123" }
}

`POST` /api/v1/agents/:id/stop

Stop a running agent pod.

Scope: agents:write

Response `200 OK`

The agent, as GET /agents/:id shows it, status stopped.

`GET` /api/v1/agents/:id/status

Get the current status of an agent pod.

Scope: agents:read

Response 200 OK

{
  "data": {
    "agentId": "pod_xyz789",
    "status": "running",
    "workflowId": "wf_abc123",
    "agentType": "function-calling",
    "toolsCount": 12
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`POST` /api/v1/agents/:id/threads

Create a new conversation thread for an agent.

Scope: agents:write

Request Body

{
  "title": "Marketing Strategy Discussion"
}

Field	Type	Required	Description
`title`	string	No	Thread title (default: "New Conversation")

Response 201 Created

{
  "data": {
    "_id": "thread_abc123",
    "agentId": "wf_abc123",
    "userId": "usr_abc",
    "title": "New Conversation",
    "messages": [],
    "metadata": {},
    "messageCount": 0,
    "totalTokens": 0,
    "createdAt": "2026-10-11T09:00:00.000Z",
    "updatedAt": "2026-10-11T09:00:00.000Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`GET` /api/v1/agents/:id/threads

List conversation threads for an agent.

Scope: agents:read

Response 200 OK

{
  "data": [
    {
      "_id": "thread_abc123",
      "agentId": "wf_abc123",
      "title": "Marketing Strategy Discussion",
      "messageCount": 24,
      "totalTokens": 15230,
      "createdAt": "2025-02-01T10:00:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ],
  "meta": {
    "requestId": "req_abc123"
  }
}

`DELETE` /api/v1/agents/:agentId/threads/:id

Delete a conversation thread.

Scope: agents:write

Response 204 No Content

`POST` /api/v1/agents/:agentId/threads/:id/runs

Run a message in one of the agent's threads and receive the response as Server-Sent Events (SSE).

Scope: agents:write

Request Body

{
  "message": "/help"
}

Field	Type	Required	Description
`message`	string	Yes	Message to send to the agent (100000 characters max)

Response 200 OK (SSE Stream)

Content-Type: text/event-stream

data: {"event":"thread.message.delta","data":{"delta":{"content":"Here are "}}}

data: {"event":"thread.message.delta","data":{"delta":{"content":"the available commands..."}}}

data: {"event":"thread.run.tool_call","data":{"name":"web-search","arguments":{"query":"..."}}}

data: {"event":"thread.run.completed","data":{"status":"completed"}}

data: [DONE]

SSE Event Types

Event	Description
`thread.message.delta`	Partial content from the agent's response
`thread.run.tool_call`	Agent is calling a tool
`thread.run.tool_result`	Tool call result
`thread.run.completed`	Agent finished processing
`thread.run.failed`	Agent encountered an error

`POST` /api/v1/workflows/:id/promote

Promote an existing workflow to an agent. The workflow must contain at least one agent node (category: agents).

Scope: agents:write

Request Body (optional)

{
  "toolWorkflowIds": ["wf_tool_1"]
}

Field	Type	Required	Description
`toolWorkflowIds`	array	No	Deployed workflows to give the agent as tools

Response 200 OK

The agent, as GET /agents/:id shows it, with warnings: what the promotion found to fix (an empty list when nothing).

`GET` /api/v1/agents/:id/skills

List skill associations for an agent. Returns each association enriched with the underlying skill's name, description, source, and tags.

Scope: agents:read

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Agent (workflow) ID

Response 200 OK

{
  "data": [
    {
      "skillId": "prompt_xyz789",
      "editable": true,
      "autoConnected": true,
      "connectedBy": "agent",
      "connectedAt": "2025-02-01T10:00:00Z",
      "name": "Web Search",
      "description": "Search the web for information",
      "source": "user",
      "tags": ["research"]
    }
  ],
  "meta": {
    "requestId": "req_abc123"
  }
}

`POST` /api/v1/agents/:id/skills

Add a skill association to an agent. If the skill is already associated, returns success without duplicating.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Agent (workflow) ID

Request Body

Field	Type	Required	Description
`skillId`	string	Yes	ID of the skill (prompt) to attach
`editable`	boolean	No	Whether the agent can edit this skill (default: `true`)
`autoConnected`	boolean	No	Whether the skill was auto-connected (default: `true`)
`connectedBy`	string	No	Who connected the skill (default: `"agent"`)

Response 201 Created: the association (200 OK with it when the skill is already attached).

{
  "data": {
    "skillId": "prompt_xyz789",
    "editable": true,
    "autoConnected": true,
    "connectedBy": "agent",
    "connectedAt": "2026-10-11T18:30:00Z"
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

`PATCH` /api/v1/agents/:agentId/skills/:id

Update the editable flag on an existing skill association.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent (workflow) ID
`id`	string	Yes	Skill ID of the association to update

Request Body

Field	Type	Required	Description
`editable`	boolean	Yes	New value for the `editable` flag

Response 200 OK: the association.

{
  "data": { "skillId": "prompt_xyz789", "editable": false, "autoConnected": true, "connectedBy": "agent", "connectedAt": "2026-10-11T18:30:00Z" },
  "meta": { "requestId": "req_abc123" }
}

`DELETE` /api/v1/agents/:agentId/skills/:id

Remove a skill association from an agent.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent (workflow) ID
`id`	string	Yes	Skill ID of the association to remove

Response 204 No Content

`DELETE` /api/v1/agents/:agentId/tool-workflows/:id

Take a tool workflow off an agent (one of its attachments.toolWorkflows). The workflow is not deleted: once no agent lists it, DELETE /api/v1/workflows/:id can delete it. A running agent loads the change when it restarts (POST /api/v1/agents/:id/redeploy).

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent (workflow) ID
`id`	string	Yes	ID of the tool workflow to take off

Response 200 OK: the agent as GET /api/v1/agents/:id shows it, without the workflow in attachments.toolWorkflows. 404 when the agent has no such tool workflow, or you cannot see the agent; 403 when you can use the agent but not change it.

`DELETE` /api/v1/agents/:agentId/addons/:id

Take an attached add-on off an agent (one of its attachments.addons). The add-on is not deleted: once nothing uses it, DELETE /api/v1/addons/:id can delete it. A running agent loads the change when it restarts.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`agentId`	string	Yes	Agent (workflow) ID
`id`	string	Yes	ID of the add-on to take off

Response 200 OK: the agent without the add-on in attachments.addons. 404 when the agent has no such add-on attached, or you cannot see the agent; 403 when you can use the agent but not change it.

Artifacts

The files an agent produces are Library artifacts linked to the agent: list them with GET /api/v1/library/artifacts?linkedIds=<agentId>, read one with GET /api/v1/library/artifacts/:id (and …/download-url for its content), save one with POST /api/v1/library/artifacts (linkedIds: ["<agentId>"]), and delete with DELETE /api/v1/library/artifacts/:id.

Knowledge

An agent answers from the knowledge bases its config lists: set them with PATCH /api/v1/agents/:id/config { "knowledgeBaseIds": [...] } and restart a running agent. GET /api/v1/agents/:id/knowledge (catalog), GET /api/v1/agents/:id/knowledge/search?q=, GET /api/v1/agents/:agentId/knowledge/documents/:id/outline and GET /api/v1/agents/:agentId/knowledge/documents/:documentId/sections/:id read its knowledge as the agent does. See the Knowledge Bases API.

`GET` /api/v1/agents/:id/analytics

Get analytics data for an agent -- sessions, token usage, success rate, and daily activity.

Scope: agents:read

Query Parameters

Parameter	Type	Required	Description
`days`	integer	No	Number of days to look back (default: 30)

Response 200 OK

{
  "data": {
    "sessionsCount": 47,
    "runsCount": 156,
    "successRate": 94,
    "avgResponseTimeMs": 8200,
    "runStatusBreakdown": { "completed": 147, "failed": 6, "inProgress": 1, "cancelled": 2 },
    "recentFailures": [
      { "runId": "run_abc123", "threadId": "thread_abc123", "error": "The model request timed out", "startedAt": "2025-02-01T13:10:00Z" }
    ],
    "toolsDetail": [
      { "name": "web_fetch", "callCount": 40, "successRate": 98, "avgDurationMs": 1200, "workflowName": null, "workflowId": null }
    ],
    "dailyRuns": [
      { "date": "2025-02-01", "runs": 12, "completed": 11, "failed": 1 }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

successRate is the percent of finished runs (completed, failed or cancelled) that completed; a run still in progress does not count, and it is null until a run has finished.

`GET` /api/v1/agents/templates

The reference agents an agent can be created from, each { key, summary }.

Scope: agents:read

Response 200 OK: every template, in one list.

`GET` /api/v1/agents/templates/:key

A reference agent's Agent Builder input (personality, operating prompt, skills, rules, connectors), to create an agent from with POST /api/v1/agents as it is or changed.

Scope: agents:read

Parameter	Type	Required	Description
`key`	string	Yes	The template's key, from the list

Response 200 OK: the template's POST /api/v1/agents body.

`GET` /api/v1/agents/:id/logs

The latest log lines of an agent's pod.

Scope: agents:read

Parameter	Type	Required	Description
`id`	string	Yes	The agent's id, or its pod's
`lines`	integer	No	How many lines (at most 2000)
`container`	string	No	A container of the pod (default the agent's)

Response 200 OK: the log lines.

`POST` /api/v1/agents/:id/demote

Turn an agent back into a regular workflow, to edit and run it as one. It only changes the mode: stop a running agent first.

Scope: agents:write

Parameter	Type	Required	Description
`id`	string	Yes	The agent

Response 200 OK: the workflow it became, as GET /workflows/:id shows it.

Agent Slash Commands

Agents support slash commands through the chat interface. These are handled by the agent's system prompt, not by the REST API. Send them as regular messages via POST /agents/:agentId/threads/:id/runs:

Command	Description
`/help`	List available commands
`/personality set <preset>`	Change communication style
`/remember <text>`	Store a memory
`/memories`	List stored memories
`/skills`	List available skills
`/skill create <name>`	Create a new skill
`/tasks`	List scheduled tasks
`/task create`	Schedule a recurring task

See individual agent documentation for agent-specific commands.

Agent Object​

GET /api/v1/agents​

GET /api/v1/agents/:id​

DELETE /api/v1/agents/:id​

PATCH /api/v1/agents/:id​

PATCH /api/v1/agents/:id/config​

GET /api/v1/agents/:id/config​

PATCH /api/v1/agents/:id/model​

POST /api/v1/agents/:id/redeploy​

Response 200 OK​

POST /api/v1/agents​

GET /api/v1/agents/name-availability​

POST /api/v1/agents/:id/start​

Response 200 OK​

POST /api/v1/agents/:id/stop​

Response 200 OK​

GET /api/v1/agents/:id/status​

POST /api/v1/agents/:id/threads​

GET /api/v1/agents/:id/threads​

DELETE /api/v1/agents/:agentId/threads/:id​

POST /api/v1/agents/:agentId/threads/:id/runs​

POST /api/v1/workflows/:id/promote​

GET /api/v1/agents/:id/skills​

POST /api/v1/agents/:id/skills​

PATCH /api/v1/agents/:agentId/skills/:id​

DELETE /api/v1/agents/:agentId/skills/:id​

DELETE /api/v1/agents/:agentId/tool-workflows/:id​

DELETE /api/v1/agents/:agentId/addons/:id​

Artifacts​

Knowledge​

GET /api/v1/agents/:id/analytics​

GET /api/v1/agents/templates​

GET /api/v1/agents/templates/:key​

GET /api/v1/agents/:id/logs​

POST /api/v1/agents/:id/demote​

Agent Slash Commands​

Agent Object

`GET` /api/v1/agents

`GET` /api/v1/agents/:id

`DELETE` /api/v1/agents/:id

`PATCH` /api/v1/agents/:id

`PATCH` /api/v1/agents/:id/config

`GET` /api/v1/agents/:id/config

`PATCH` /api/v1/agents/:id/model

`POST` /api/v1/agents/:id/redeploy

Response `200 OK`

`POST` /api/v1/agents

`GET` /api/v1/agents/name-availability

`POST` /api/v1/agents/:id/start

Response `200 OK`

`POST` /api/v1/agents/:id/stop

Response `200 OK`

`GET` /api/v1/agents/:id/status

`POST` /api/v1/agents/:id/threads

`GET` /api/v1/agents/:id/threads

`DELETE` /api/v1/agents/:agentId/threads/:id

`POST` /api/v1/agents/:agentId/threads/:id/runs

`POST` /api/v1/workflows/:id/promote

`GET` /api/v1/agents/:id/skills

`POST` /api/v1/agents/:id/skills

`PATCH` /api/v1/agents/:agentId/skills/:id

`DELETE` /api/v1/agents/:agentId/skills/:id

`DELETE` /api/v1/agents/:agentId/tool-workflows/:id

`DELETE` /api/v1/agents/:agentId/addons/:id

Artifacts

Knowledge

`GET` /api/v1/agents/:id/analytics

`GET` /api/v1/agents/templates

`GET` /api/v1/agents/templates/:key

`GET` /api/v1/agents/:id/logs

`POST` /api/v1/agents/:id/demote

Agent Slash Commands