Skip to main content
POST
/
api
/
agents
Create agent
curl --request POST \
  --url https://api.example.com/api/agents \
  --header 'Content-Type: application/json' \
  --data '
{
  "agent_type": "<string>",
  "name": "<string>",
  "description": "<string>",
  "instructions": "<string>"
}
'
Creates a new agent under the authenticated user’s default organization.

​
Request body

​
agent_type
string
required
Agent type. One of: generic, concierge, collections, onboarding, renewal.
​
name
string
required
Display name for the agent. 1–128 characters.
​
description
string
Short description of the agent’s purpose.
​
instructions
string
Natural-language instructions that define the agent’s behavior, goals, and constraints.

​
Minimal request

{
  "agent_type": "concierge",
  "name": "Collections Agent"
}

​
Full request

{
  "agent_type": "collections",
  "name": "Collections Agent",
  "description": "Follows up on overdue invoices via email",
  "instructions": "You are a collections agent. When triggered by an overdue invoice, draft a professional follow-up email to the billing contact."
}

​
Response

Returns 201 with the full agent detail: 
{
  "status": "success",
  "status_code": 201,
  "message": "Agent created",
  "data": {
    "uid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "organization_uid": "550e8400-e29b-41d4-a716-446655440000",
    "agent_type": "collections",
    "name": "Collections Agent",
    "description": "Follows up on overdue invoices via email",
    "instructions": "You are a collections agent...",
    "status": "draft",
    "created_by_uid": "660e8400-e29b-41d4-a716-446655440000",
    "notification_config": null,
    "runs_count": 0,
    "created_on": "2026-03-20T10:00:00Z",
    "updated_on": "2026-03-20T10:00:00Z",
    "triggers": [],
    "tools": []
  }
}
New agents start in draft status with no triggers or tools. Configure triggers and tools, then update the status to active to begin automated runs.