Skip to main content
POST
/
api
/
agents
Create a new agent
curl --request POST \
  --url http://localhost:3000/api/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Support Agent",
  "instructions": "You are a helpful customer support agent...",
  "description": "An AI agent that helps customers with their inquiries",
  "policy": "Refunds are only allowed within 30 days of purchase. Escalate complaints about billing errors to a human agent.",
  "modelConfig": {
    "model": "openai/gpt-4o",
    "modelSettings": {
      "temperature": 0.7
    }
  },
  "voiceConfig": {
    "pipelineMode": "batch",
    "voiceId": "EXAVITQdyfvLewQXW32eyLI"
  },
  "memoryConfig": {
    "enabled": true,
    "lastMessages": 20
  },
  "metadata": {
    "category": "support"
  },
  "knowledgeBaseConfig": {
    "knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
    "topK": 5,
    "similarityThreshold": 0.7
  },
  "resolutionCriteria": [
    {
      "label": "Payment confirmed",
      "description": "Customer confirms the payment date and amount"
    }
  ]
}
'
{
  "id": "<string>",
  "organizationId": "<string>",
  "name": "Customer Support Agent",
  "instructions": "<string>",
  "status": "draft",
  "version": 123,
  "modelConfig": {
    "model": "openai/gpt-4o",
    "modelSettings": {},
    "providerOptions": {}
  },
  "createdAt": "2023-11-07T05:31:56Z",
  "updatedAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "policy": "<string>",
  "metadata": {},
  "knowledgeBaseConfig": {},
  "createdBy": "<string>"
}

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
name
string
required

Agent name

Required string length: 1 - 128
Example:

"Customer Support Agent"

instructions
string
required

Agent instructions (system prompt)

Maximum string length: 10000
Example:

"You are a helpful customer support agent..."

description
string

Agent description

Maximum string length: 2000
Example:

"An AI agent that helps customers with their inquiries"

policy
string

Agent policy — business rules auto-injected into the prompt (hidden from callers)

Maximum string length: 10000
Example:

"Refunds are only allowed within 30 days of purchase. Escalate complaints about billing errors to a human agent."

modelConfig
object

Model configuration

Example:
{
"model": "openai/gpt-4o",
"modelSettings": { "temperature": 0.7 }
}
voiceConfig
object

Voice pipeline configuration

Example:
{
"pipelineMode": "batch",
"voiceId": "EXAVITQdyfvLewQXW32eyLI"
}
memoryConfig
object

Memory configuration

Example:
{ "enabled": true, "lastMessages": 20 }
metadata
object

Additional metadata

Example:
{ "category": "support" }
knowledgeBaseConfig
object

Knowledge base configuration for RAG

Example:
{
"knowledgeBaseId": "550e8400-e29b-41d4-a716-446655440000",
"topK": 5,
"similarityThreshold": 0.7
}
resolutionCriteria
object[]

Resolution criteria for evaluating conversation outcomes (max 5)

Example:
[
{
"label": "Payment confirmed",
"description": "Customer confirms the payment date and amount"
}
]

Response

Agent created successfully

id
string
required

Agent ID

organizationId
string
required

Organization ID

name
string
required

Agent name

Example:

"Customer Support Agent"

instructions
string
required

Agent instructions

status
enum<string>
required

Agent status

Available options:
draft,
active,
archived
version
number
required

Agent version

modelConfig
object
required

Model configuration

createdAt
string<date-time>
required

Created at timestamp

updatedAt
string<date-time>
required

Updated at timestamp

description
string | null

Agent description

policy
string | null

Agent policy (business rules)

voiceConfig
object

Voice configuration

memoryConfig
object

Memory configuration

metadata
object

Additional metadata

knowledgeBaseConfig
object

Knowledge base configuration for RAG

createdBy
string | null

Created by user ID