Skip to main content
POST
/
ai-agents
/
agents
Create BYO Agent
curl --request POST \
  --url https://{appId}.api-{region}.cometchat.io/v3/ai-agents/agents \
  --header 'Content-Type: application/json' \
  --header 'apikey: <api-key>' \
  --data '
{
  "name": "My Mastra Agent",
  "icon": "<string>",
  "isActive": true,
  "tools": [
    "<string>"
  ],
  "actions": [
    "<string>"
  ],
  "metaData": {
    "greetingMessage": "<string>",
    "introductoryMessage": "<string>",
    "suggestedMessages": [
      "<string>"
    ]
  }
}
'
{
  "agent": {
    "uid": "550e8400-e29b-41d4-a716-446655440000",
    "appId": "my-app-id",
    "name": "My Agent",
    "icon": "https://example.com/icon.png",
    "isActive": true,
    "integrateWith": "openai",
    "integrationType": "agent",
    "tools": [
      "tool1"
    ],
    "actions": [
      "action1"
    ],
    "instruction": "You are a helpful assistant",
    "integrationMeta": {},
    "metaData": {},
    "deletedAt": null,
    "createdAt": "2025-12-01T00:00:00.000Z",
    "updatedAt": "2025-12-01T00:00:00.000Z"
  }
}
For the complete error reference, see Error Guide.

Authorizations

​
apikey
string
header
required

API Key (i.e. Rest API Key from the Dashboard).

Headers

​
chatApiVersion
string
default:v3.0

Chat API version. Defaults to v3.0.

Body

application/json
​
name
string
required

Name of the agent

Example:

"My Mastra Agent"

​
icon
string<url>
required

URL to the icon/avatar of the agent

​
integrateWith
enum<string>
required

Integration platform identifier

Available options:
mastra
​
integrationType
enum<string>
required

Type of connection

Available options:
agent
​
isActive
boolean
default:true

Whether the agent is active

​
integrationMeta
object

Mastra-specific configuration

​
tools
string[]

List of tool names (must exist in the app's tools)

​
actions
string[]

List of action names (must exist in the app's actions)

​
metaData
object

Metadata for the agent

Response

201 - application/json

Agent created successfully

​
agent
object