curl --request POST \
--url https://www.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"
}Create or update an agent
Create a new agent or update an existing one.
- Create: Omit
idfrom the request body. Requiresorg:manage_agents:createpermission ororg:adminrole. - Update: Include the agent’s
idin the request body. Requiresorg:manage_agents:updatepermission ororg:adminrole.
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.
curl --request POST \
--url https://www.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
Body
How hard the model reasons. Omit to leave unchanged; null uses the model's default. Rejected with 400 when the agent's model doesn't offer that level, including when you change model and the saved level doesn't fit the new one.
low, medium, high "low"
Tool definitions keyed by tool name (e.g., scrape_url,
search_knowledge_base). Two shapes are accepted:
- Native tools:
{ description, parameters }— copy these fromGET /tools. Schemas are refreshed to the latest platform definitions on save. - Provider tools (e.g.,
google:code_execution):{ "isProviderTool": true }keyed under theprovider:toolname.
Per-tool config (e.g., callableAgentIds for call_agent,
accessibleKnowledgeBaseIds for search_knowledge_base)
can be set under a config field and is preserved by
POST /agents/sync-tools.
Call GET /tools to discover the names and parameter
shapes available to the org.
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.) and
cannot match the agent-{id} or kb-{id} system patterns.
63^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$"support-bot"
Response
Agent created or updated successfully