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",
  "description": "AI Chief Marketing Officer with brand strategy and content creation",
  "status": "running",
  "agent_id": "pod_xyz789",
  "agent_type": "function-calling",
  "tools_count": 12,
  "memory_types": ["conversation", "episodic"],
  "config": {
    "temperature": 0.7,
    "max_iterations": 15
  },
  "live_state": {
    "current_activity": "idle"
  },
  "created_at": "2025-01-15T10:30:00Z",
  "last_activity": "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
`search`	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)
`offset`	integer	No	Number of results to skip (default: 0)
`sort`	string	No	Sort field and direction, e.g. `-createdAt`

Response 200 OK

{
  "data": [
    {
      "_id": "wf_abc123",
      "name": "C-Suite CMO",
      "description": "AI Chief Marketing Officer",
      "status": "running",
      "agent_id": "pod_xyz789",
      "agent_type": "function-calling",
      "tools_count": 12,
      "last_activity": "2025-02-01T14:22:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ],
  "meta": {
    "total": 3,
    "limit": 50,
    "offset": 0,
    "hasMore": false
  }
}

`POST` /api/v1/agents

Create a new agent. Creates a workflow in agent mode.

Scope: agents:write

Request Body

{
  "name": "C-Suite CMO",
  "description": "AI Chief Marketing Officer with brand strategy and content creation",
  "nodes": [
    {
      "id": "trigger",
      "type": "triggers/webhook",
      "label": "Chat Trigger",
      "category": "triggers",
      "config": {}
    },
    {
      "id": "agent-node",
      "type": "agents/function-calling",
      "label": "CMO Agent",
      "category": "agents",
      "config": {
        "systemPrompt": "You are the Chief Marketing Officer...",
        "temperature": 0.7,
        "maxIterations": 15
      }
    }
  ],
  "connections": [
    {
      "source": "trigger",
      "sourcePort": "output",
      "target": "agent-node",
      "targetPort": "input"
    }
  ]
}

Field	Type	Required	Description
`name`	string	Yes	Agent name
`description`	string	No	Agent description
`nodes`	array	No	Workflow nodes (must include an agent node for agent features)
`connections`	array	No	Node connections

Response 201 Created

{
  "data": {
    "workflowId": "wf_abc123",
    "mode": "agent"
  }
}

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

Get detailed agent information including live status, config, and nodes.

Scope: agents:read

Response 200 OK

{
  "data": {
    "_id": "wf_abc123",
    "name": "C-Suite CMO",
    "description": "AI Chief Marketing Officer",
    "mode": "agent",
    "status": "running",
    "agent_id": "pod_xyz789",
    "agent_type": "function-calling",
    "tools_count": 12,
    "memory_types": ["conversation", "episodic"],
    "config": { "temperature": 0.7 },
    "live_state": { "current_activity": "idle" },
    "nodes": [...],
    "connections": [...],
    "created_at": "2025-01-15T10:30:00Z",
    "last_activity": "2025-02-01T14:22:00Z"
  }
}

`PUT` /api/v1/agents/:id

Update an agent's configuration, name, description, or nodes.

Scope: agents:write

Request Body

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "config": {
    "maxIterations": 20
  }
}

Response 200 OK

{
  "data": { "success": true, "updated": "wf_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

Partial update of an agent. Accepts brain-config keys (personality, operating prompt id, context policy, session policy, heartbeat, max iterations) and/or workflow-level fields (name, description, nodes, connections) in a single flat body.

Operating-prompt changes live-reload on the agent's next turn. Every other change requires a redeploy — call POST /agents/:id/redeploy afterwards.

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,
  "name": "Iris",
  "description": "Personal assistant"
}

Response 200 OK

{ "data": { "success": true, "updated": "wf_abc123" } }

`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"]
    }
  }
}

`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"]
  }
}

`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

{ "data": { "success": true, "restarted": true } }

`POST` /api/v1/agents/create-from-wizard

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. When operatingPromptId is omitted the platform default is used. When personality is omitted the platform DEFAULT_PERSONALITY is used.

Response 201 Created

{
  "data": {
    "workflowId": "wf_new",
    "seedCounts": { "memory": 0, "rules": 1, "skills": 0, "tasks": 0 },
    "attachedAddons": { "mongodb": "addon_xyz" },
    "operatingPromptId": "prompt_default_op_resolved"
  }
}

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

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

`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

{
  "data": {
    "success": true,
    "agent_id": "pod_xyz789",
    "pod_ip": "172.31.42.100"
  }
}

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

Stop a running agent pod.

Scope: agents:write

Response 200 OK

{
  "data": { "success": true }
}

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

Get the current status of an agent pod.

Scope: agents:read

Response 200 OK

{
  "data": {
    "agent_id": "pod_xyz789",
    "status": "running",
    "workflow_id": "wf_abc123",
    "agent_type": "function-calling",
    "tools_count": 12
  }
}

`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": {
    "success": true,
    "thread_id": "thread_abc123"
  }
}

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

List conversation threads for an agent.

Scope: agents:read

Response 200 OK

{
  "data": [
    {
      "_id": "thread_abc123",
      "agent_id": "pod_xyz789",
      "title": "Marketing Strategy Discussion",
      "message_count": 24,
      "total_tokens": 15230,
      "created_at": "2025-02-01T10:00:00Z",
      "updated_at": "2025-02-01T14:22:00Z"
    }
  ]
}

`DELETE` /api/v1/agents/:id/threads?threadId=thread_abc123

Delete a conversation thread.

Scope: agents:write

Query Parameters

Parameter	Type	Required	Description
`threadId`	string	Yes	ID of the thread to delete

Response 204 No Content

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

Send a message to an agent and receive a streaming response via Server-Sent Events (SSE).

Scope: agents:write

Request Body

{
  "threadId": "thread_abc123",
  "message": "/help"
}

Field	Type	Required	Description
`threadId`	string	Yes	Thread ID for the conversation
`message`	string	Yes	Message to send to the agent

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/agents/promote

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

Scope: agents:write

Request Body

{
  "workflowId": "wf_abc123"
}

Field	Type	Required	Description
`workflowId`	string	Yes	ID of the workflow to promote

Response 200 OK

{
  "data": {
    "success": true,
    "workflowId": "wf_abc123"
  }
}

`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"]
    }
  ]
}

`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

{
  "data": {
    "success": true,
    "skillId": "prompt_xyz789"
  }
}

`PUT` /api/v1/agents/:id/skills/:sub

Update the editable flag on an existing skill association.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Agent (workflow) ID
`sub`	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

{
  "data": { "success": true }
}

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

Remove a skill association from an agent.

Scope: agents:write

Path Parameters

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

Response 204 No Content

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

List artifacts produced by an agent. Returns metadata only (content excluded for list payload size). Capped at 100 items, sorted by created_at descending.

Scope: agents:read

Path Parameters

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

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by artifact type (e.g. `html_report`)
`tag`	string	No	Filter by tag

Response 200 OK

{
  "data": [
    {
      "_id": "art_abc123",
      "agent_id": "wf_abc123",
      "thread_id": "thread_001",
      "title": "Q4 Marketing Plan",
      "artifact_type": "html_report",
      "summary": "Quarterly marketing roadmap",
      "skill_id": null,
      "tags": ["marketing", "q4"],
      "metadata": {},
      "created_at": "2025-02-01T14:00:00Z",
      "updated_at": "2025-02-01T14:00:00Z"
    }
  ]
}

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

Get a single artifact including its full content field.

Scope: agents:read

Path Parameters

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

Response 200 OK

{
  "data": {
    "_id": "art_abc123",
    "agent_id": "wf_abc123",
    "thread_id": "thread_001",
    "title": "Q4 Marketing Plan",
    "artifact_type": "html_report",
    "content": "<html>...</html>",
    "summary": "Quarterly marketing roadmap",
    "skill_id": null,
    "tags": ["marketing", "q4"],
    "metadata": {},
    "created_at": "2025-02-01T14:00:00Z",
    "updated_at": "2025-02-01T14:00:00Z"
  }
}

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

Save a new artifact for an agent (e.g. a generated HTML report, document, or data file).

Scope: agents:write

Path Parameters

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

Request Body

Field	Type	Required	Description
`title`	string	Yes	Artifact title
`content`	string	Yes	Artifact content (e.g. HTML, markdown, JSON)
`artifact_type`	string	No	Type identifier (default: `"html_report"`)
`thread_id`	string	No	Associated thread ID
`summary`	string	No	Short summary of the artifact
`skill_id`	string	No	Skill that produced this artifact
`tags`	string[]	No	Tags for categorization
`metadata`	object	No	Arbitrary metadata

Response 201 Created

{
  "data": {
    "artifactId": "art_abc123",
    "title": "Q4 Marketing Plan",
    "artifact_type": "html_report"
  }
}

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

Delete an artifact.

Scope: agents:write

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Agent (workflow) ID
`sub`	string	Yes	Artifact ID to delete

Response 200 OK

{
  "data": { "deleted": true }
}

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

Upload a document to the agent's knowledge base. Accepts multipart/form-data with a file field. Bytes are forwarded to the agent's knowledge-upload workflow webhook, which handles parsing (PDF/PPTX/TXT, OCR), chunking, embedding, and Milvus storage. No file parsing or S3 storage happens in Meteor.

Scope: agents:write

Path Parameters

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

Request (multipart/form-data)

Field	Type	Required	Description
`file`	file	Yes	Document binary (PDF/PPTX/TXT/etc.)
`documentId`	string	No	Caller-supplied document ID (default: auto-generated)
`tags`	string	No	Tag metadata to attach to the document
`description`	string	No	Optional description for the document

Response 201 Created

{
  "data": {
    "documentId": "doc_1738431600_a1b2c3",
    "filename": "playbook.pdf",
    "fileSize": 1048576,
    "executionId": "exec_xyz789",
    "status": "processing"
  }
}

Errors

Status	Code	Description
`400`	`validation-error`	Missing or unreadable file
`404`	`not-found`	Agent not found
`422`	`not-configured`	Agent has no knowledge-upload workflow configured
`502`	`ingest-error`	Knowledge workflow rejected or failed the upload

`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": {
    "sessions_count": 47,
    "runs_count": 156,
    "success_rate": 0.94,
    "total_tokens": 245000,
    "total_cost_usd": 12.50,
    "daily_runs": [
      { "date": "2025-02-01", "count": 12 }
    ]
  }
}

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/:id/chat:

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
`/knowledge search <query>`	Search the knowledge base

See individual agent documentation for agent-specific commands.

Agent Object​

GET /api/v1/agents​

POST /api/v1/agents​

GET /api/v1/agents/:id​

PUT /api/v1/agents/:id​

DELETE /api/v1/agents/:id​

PATCH /api/v1/agents/:id​

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

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

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

POST /api/v1/agents/create-from-wizard​

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

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

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

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

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

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

DELETE /api/v1/agents/:id/threads?threadId=thread_abc123​

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

POST /api/v1/agents/promote​

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

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

PUT /api/v1/agents/:id/skills/:sub​

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

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

GET /api/v1/agents/:id/artifacts/:sub​

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

DELETE /api/v1/agents/:id/artifacts/:sub​

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

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

Agent Slash Commands​

Agent Object

`GET` /api/v1/agents

`POST` /api/v1/agents

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

`PUT` /api/v1/agents/:id

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

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

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

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

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

`POST` /api/v1/agents/create-from-wizard

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

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

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

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

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

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

`DELETE` /api/v1/agents/:id/threads?threadId=thread_abc123

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

`POST` /api/v1/agents/promote

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

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

`PUT` /api/v1/agents/:id/skills/:sub

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

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

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

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

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

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

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

Agent Slash Commands