Skip to main content
POST
/
api
/
v1
/
agents
/
cURL
curl --request POST \
  --url https://alpha-plagiocephalic-darrell.ngrok-free.dev/api/v1/agents/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '
{
  "name": "<string>"
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "name": "<string>",
  "systemPrompt": "<string>",
  "firstMessage": "<string>",
  "profilePicture": "<string>",
  "tools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "description": "<string>",
      "apiSchema": "<unknown>",
      "creditCost": 123,
      "active": true
    }
  ],
  "documents": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "file": "<string>",
      "status": "<string>"
    }
  ],
  "memoryKeys": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "key": "<string>",
      "type": "<string>",
      "initialValue": "<string>",
      "whenToUpdate": "<string>"
    }
  ],
  "wakeUpConfigs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "description": "<string>",
      "forceMessage": true,
      "enabled": true
    }
  ],
  "outboundTriggers": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "templateId": "<string>",
      "templateName": "<string>",
      "secret": "<string>",
      "enabled": true
    }
  ],
  "websiteTools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "url": "<string>",
      "prompt": "<string>",
      "active": true
    }
  ],
  "imageGenerateTools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "prompt": "<string>",
      "creditCost": 123,
      "name": "<string>",
      "description": "<string>",
      "active": true
    }
  ],
  "handoffTools": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "parentAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "childAgentId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "childAgentName": "<string>",
      "description": "<string>",
      "active": true
    }
  ],
  "mcpConfigs": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "connectorId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "connectorName": "<string>",
      "toolWhitelist": "<unknown>"
    }
  ],
  "paywallConfig": "<string>",
  "adConfig": "<string>",
  "creditSettings": "<string>",
  "voiceCallConfig": "<string>",
  "owner": "<string>",
  "sharings": "<string>",
  "phoneNumbers": [
    {
      "whatsappPhoneNumberId": "<string>",
      "whatsappBusinessAccountId": "<string>",
      "wabaId": "<string>",
      "phoneNumber": "<string>"
    }
  ],
  "totalMessages": "<string>",
  "totalSessions": "<string>",
  "connectUrl": "<string>",
  "ownerActive": "<string>",
  "createdAt": "2023-11-07T05:31:56Z",
  "description": "<string>",
  "icebreakers": "<unknown>",
  "llmModel": "<string>"
}
This endpoint lets you create a new agent.

​
Tool Input Types

When defining a tool’s api_schema, every parameter (in path_params, query_params, request_headers, or request_body) takes an input object that tells the platform where the value should come from at call time. There are two input types:
The agent extracts the value from the conversation based on the description you provide.
"message": {
  "type": "string",
  "input": {
    "type": "description",
    "description": "The exact message sent by the customer"
  }
}
Use a literal value, or a built-in template variable that gets substituted at call time. Template variables are written as %VARIABLE_NAME%.
"phone_number": {
  "type": "string",
  "input": {
    "type": "value",
    "value": "%PHONE_NUMBER%"
  }
}
You can also pass any plain string (e.g. an API key, a fixed endpoint, a constant flag):
"Authorization": {
  "type": "string",
  "input": {
    "type": "value",
    "value": "Bearer sk-live-..."
  }
}

​
Built-in Template Variables

When an input of type: "value" contains one of the following tokens, the platform replaces it with the appropriate runtime value before the tool is invoked:
VariableReplaced with
%PHONE_NUMBER%The customer’s WhatsApp phone number for the current session
%IMAGE_URL%The URL of the most recent image the customer sent (if the triggering message was an image)
%CALLBACK_URL%A unique callback URL for this tool invocation — POST to it to send a follow-up message back into the conversation
Tokens are substituted anywhere they appear inside a string value, so you can interpolate them into URLs, headers, query params, and request body fields.

​
Example

A forward_message tool that posts the customer’s phone number, message text, attached image, and a reply callback to your own webhook: 
{
  "url": "https://your-app.example.com/webhooks/agent",
  "method": "POST",
  "path_params": {},
  "query_params": { "required": [], "properties": {} },
  "request_body": {
    "type": "object",
    "required": [],
    "properties": {
      "phone_number": {
        "type": "string",
        "input": { "type": "value", "value": "%PHONE_NUMBER%" }
      },
      "message": {
        "type": "string",
        "input": {
          "type": "description",
          "description": "The exact message sent by the customer"
        }
      },
      "image": {
        "type": "string",
        "input": { "type": "value", "value": "%IMAGE_URL%" }
      },
      "reply_callback": {
        "type": "string",
        "input": { "type": "value", "value": "%CALLBACK_URL%" }
      }
    }
  }
}
%IMAGE_URL% is only populated when the message that triggered the tool call was an image. For text-only messages the field is omitted from the outgoing request.

Authorizations

​
X-API-Key
string
header
required

API key authentication. Pass your API key in the X-API-Key header.

Body

application/json
​
name
string
required
Maximum string length: 255

Response

201 - application/json
​
id
string<uuid>
required
read-only
​
name
string
required
Maximum string length: 255
​
systemPrompt
string
required
​
firstMessage
string
required
​
profilePicture
string
required
read-only
​
tools
object[]
required
read-only
​
documents
object[]
required
read-only
​
memoryKeys
object[]
required
read-only
​
wakeUpConfigs
object[]
required
read-only
​
outboundTriggers
object[]
required
read-only
​
websiteTools
object[]
required
read-only
​
imageGenerateTools
object[]
required
read-only
​
handoffTools
object[]
required
read-only
​
mcpConfigs
object[]
required
read-only
​
paywallConfig
string
required
read-only
​
adConfig
string
required
read-only
​
creditSettings
string
required
read-only
​
voiceCallConfig
string
required
read-only
​
owner
string
required
read-only
​
sharings
string
required
read-only
​
phoneNumbers
object[]
required
read-only
​
totalMessages
string
required
read-only
​
totalSessions
string
required
read-only
​
connectUrl
string
required
read-only
​
ownerActive
string
required
read-only
​
createdAt
string<date-time>
required
read-only
​
description
string
​
icebreakers
any
​
llmModel
string | null