curl --request POST \
  --url https://asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "model": "openai:gpt-4o",
  "systemPrompt": "You are a helpful customer support agent.",
  "conversationStarters": [
    "How can I help you today?"
  ],
  "stage": "development",
  "showInChat": true
}
'

{
  "id": 1,
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "logoUrl": null,
  "conversationStarters": [
    "How can I help you today?"
  ],
  "model": "openai:gpt-4o",
  "maxToolRoundtrips": 50,
  "systemPrompt": "You are a helpful customer support agent.",
  "tools": {},
  "mcpServers": null,
  "stage": "development",
  "showInChat": true,
  "emailSlug": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Agents API

Create or update an agent

Create a new agent or update an existing one.

Create: Omit id from the request body. Requires org:manage_agents:create permission or org:admin role.
Update: Include the agent’s id in the request body. Requires org:manage_agents:update permission or org:admin role.

Cloning an agent: There is no dedicated clone endpoint. To clone an agent, GET /agents to retrieve the original, modify the payload (e.g., change the name), and POST /agents without an id to create it as a new agent.

Tool schemas are automatically refreshed to match the latest platform definitions when saving.

POST

agents

curl --request POST \
  --url https://asteragents.com/api/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "model": "openai:gpt-4o",
  "systemPrompt": "You are a helpful customer support agent.",
  "conversationStarters": [
    "How can I help you today?"
  ],
  "stage": "development",
  "showInChat": true
}
'

{
  "id": 1,
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "logoUrl": null,
  "conversationStarters": [
    "How can I help you today?"
  ],
  "model": "openai:gpt-4o",
  "maxToolRoundtrips": 50,
  "systemPrompt": "You are a helpful customer support agent.",
  "tools": {},
  "mcpServers": null,
  "stage": "development",
  "showInChat": true,
  "emailSlug": null,
  "createdAt": "2024-01-15T10:30:00.000Z",
  "updatedAt": "2024-01-15T10:30:00.000Z"
}

Authorizations

Authorization

string

header

required

JWT token from Clerk authentication.

Must be from a user with org:admin role.

Body

application/json

name

string

required

Agent name

Example:

"Customer Support Agent"

integer

Agent ID — include to update an existing agent, omit to create a new one

Example:

1

description

string

Short description of the agent's purpose

Example:

"Handles customer inquiries and support tickets"

logoUrl

string

URL to the agent's logo image

conversationStarters

string[]

Suggested conversation starters shown to users

Example:

[
  "How can I help you today?",
  "What issue are you experiencing?"
]

model

string

Model identifier (e.g., openai:gpt-4o, anthropic:claude-sonnet-4-20250514)

Example:

"openai:gpt-4o"

maxToolRoundtrips

integer

Maximum number of tool call roundtrips per response

Required range: x >= 1

Example:

50

systemPrompt

string

System prompt / instructions for the agent

Example:

"You are a helpful customer support agent. Be friendly and concise."

tools

object

Tool definitions keyed by tool name. Each tool has a description and parameters schema. Tool schemas are refreshed to latest platform definitions on save.

integrations

string[]

List of enabled integration identifiers

mcpServers

string[]

List of MCP server IDs to connect

stage

enum<string>

default:development

Agent lifecycle stage

Available options:

development,

released

showInChat

boolean

default:true

Whether the agent appears in the chat interface

emailSlug

string | null

Custom email slug for the agent's email address. Must be lowercase alphanumeric with hyphens, cannot start or end with a hyphen, max 63 characters. Must be unique across all agents. Cannot use reserved slugs (admin, support, help, noreply, postmaster, etc.).

Maximum string length: 63

Example:

"support-bot"

tagIds

integer[]

Tag IDs to associate with this agent (must belong to the organization)

Example:

[1, 2]

Response

Agent created or updated successfully

integer

required

Unique agent identifier

Example:

1

name

string

required

Agent name

Example:

"Customer Support Agent"

stage

enum<string>

required

Agent lifecycle stage

Available options:

development,

released

Example:

"development"

showInChat

boolean

required

Whether the agent appears in the chat interface

Example:

true

createdAt

string<date-time>

required

When the agent was created

Example:

"2024-01-15T10:30:00.000Z"

updatedAt

string<date-time>

required

When the agent was last updated

Example:

"2024-01-20T14:00:00.000Z"

description

string | null

Short description of the agent's purpose

Example:

"Handles customer inquiries and support tickets"

logoUrl

string | null

URL to the agent's logo image

conversationStarters

string[] | null

Suggested conversation starters shown to users

Example:

[
  "How can I help you today?",
  "What issue are you experiencing?"
]

model

string | null

Model identifier (e.g., openai:gpt-4o)

Example:

"openai:gpt-4o"

maxToolRoundtrips

integer | null

Maximum number of tool call roundtrips per response

Example:

50

systemPrompt

string | null

System prompt / instructions for the agent

tools

object

Tool definitions keyed by tool name

mcpServers

string[] | null

Connected MCP server IDs

emailSlug

string | null

Custom email slug for the agent's email address

Example:

"support-bot"

API Documentation

Admin API

Files API

Agents API

Agent Tags API

Knowledge Bases API

Conversations API

Other Endpoints

Legacy Endpoints (Deprecated)

Create or update an agent

Authorizations

Body

Response