Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

A personal API key or an OAuth 2.0 access token. Personal API keys also require the x-auth-key header with your user ID.

Body

application/json
name
string
required

Display name for the agent.

Example:

"Sales research agent"

model_name
string | null

ID of the LLM the agent runs on. Use GET /models to discover valid values. Omit for the organization's default agent model.

Example:

"anthropic/claude-sonnet-4"

description
string | null
Example:

"Researches accounts and drafts outreach"

system_prompt
string | null
Example:

"You are a B2B sales research assistant."

tools
object[]

Connectors and native abilities to start with. The platform's default native abilities are added behind whatever you send. Prefer PUT /agents/{agent_id}/mcp-servers/{server_id} and PATCH /agents/{agent_id}/abilities after creation.

resources
object[]

Resources attached to the agent.

skill_ids
string[] | null

IDs of skills to attach to the agent. Attachment happens inside the create transaction, so an invalid ID fails the whole request (no orphaned agent). Omit to attach none. The caller must hold INVOKE on each skill. After creation, manage skills with PATCH /agents/{agent_id}/skills.

Example:
knowledge_sources
object[] | null

Brain sources to attach, with an optional scope each. Attached inside the create transaction, like skill_ids. Omit config for the whole source.

Example:
metadata
object | null

Agent settings. Omitted sections take the organization's agent defaults.

folder_id
string | null

ID of the folder to place the agent in.

Example:

"folder_91ab"

is_active
boolean
default:true

Whether the agent is active. Defaults to true.

Setting this to false retires the agent: it disappears from GET /agents, and GET/PATCH /agents/{agent_id} return 404, so it cannot be reactivated through the API. This is not a pause switch — to stop an agent from running while keeping it reachable, disable its triggers instead.

agent_id
string | null

Optional caller-supplied agent ID. When omitted, the server generates one.

team_id
string | null

ID of the team to create the agent under. When omitted, the agent is owned by the authenticated user.

Example:

"team_4f8c92ab"

Response

Agent created.

agent
object

An agent and its whole configuration. Single-agent retrieve, create and update return this shape; the list endpoint does not populate the inlined collections, abilities or version. Collection-specific writes return their own result shapes.