> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## OpenAPI
````yaml /openapi.yaml post /agents
openapi: 3.1.0
info:
title: AsterAgents API
version: 1.0.0
description: >
API for AsterAgents platform operations.
- **Admin endpoints** (`/admin/*`) require organization admin privileges
(`org:admin` role)
- **Agent endpoints** (`/agents`) require agent management permissions or
`org:admin` role
- **Knowledge base endpoints** (`/kb/*`) require standard authentication
- **Skills endpoints** (`/skills/*`) require standard authentication
- **File endpoints** (`/upload/*`, `/kb/files`, `/skills/files`) require
standard authentication
contact:
name: AsterAgents Support
url: https://asteragents.com/support
servers:
- url: https://asteragents.com/api
description: Production
- url: http://localhost:3000/api
description: Local development
security:
- bearerAuth: []
tags:
- name: Users
description: Manage active organization users
- name: Invitations
description: Manage organization invitations
- name: Files
description: Upload and manage files
- name: Knowledge Bases
description: Manage knowledge bases and their files
- name: Knowledge Base Management
description: Create, update, and delete knowledge bases
- name: Agents
description: Create, update, and delete agents
- name: Agent Tags
description: Organize agents with tags
- name: Tools
description: Discover the tool catalog available to your organization
- name: Skills
description: Manage agent skills
- name: Skill Files
description: Manage bundled files for skills
- name: Conversations
description: Invoke agents and retrieve conversation history and messages
- name: Scheduled Tasks
description: Schedule agents to run automatically on a cron schedule
paths:
/agents:
post:
tags:
- Agents
summary: Create or update an agent
description: >
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.
operationId: saveAgent
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
id:
type: integer
description: >-
Agent ID — include to update an existing agent, omit to
create a new one
example: 1
name:
type: string
description: Agent name
example: Customer Support Agent
description:
type: string
description: Short description of the agent's purpose
example: Handles customer inquiries and support tickets
logoUrl:
type: string
description: URL to the agent's logo image
conversationStarters:
type: array
description: Suggested conversation starters shown to users
items:
type: string
example:
- How can I help you today?
- What issue are you experiencing?
model:
type: string
description: >-
Model identifier (e.g., `openai:gpt-4o`,
`anthropic:claude-sonnet-4-20250514`)
example: openai:gpt-4o
maxToolRoundtrips:
type: integer
minimum: 1
description: Maximum number of tool call roundtrips per response
example: 50
systemPrompt:
type: string
description: System prompt / instructions for the agent
example: >-
You are a helpful customer support agent. Be friendly and
concise.
tools:
type: object
description: |
Tool definitions keyed by tool name (e.g., `scrape_url`,
`search_knowledge_base`). Two shapes are accepted:
- **Native tools**: `{ description, parameters }` — copy
these from `GET /tools`. Schemas are refreshed to the
latest platform definitions on save.
- **Provider tools** (e.g., `google:code_execution`):
`{ "isProviderTool": true }` keyed under the `provider:tool` name.
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.
additionalProperties: true
integrations:
type: array
description: List of enabled integration identifiers
items:
type: string
mcpServers:
type: array
description: >-
List of MCP server IDs to connect (integer mcp_server.id
values)
items:
type: integer
stage:
type: string
description: Agent lifecycle stage
enum:
- development
- released
default: development
showInChat:
type: boolean
description: Whether the agent appears in the chat interface
default: true
emailSlug:
type: string
nullable: true
description: >
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.
pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$
maxLength: 63
example: support-bot
tagIds:
type: array
description: >-
Tag IDs to associate with this agent (must belong to the
organization)
items:
type: integer
example:
- 1
- 2
examples:
create:
summary: Create a new agent
value:
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
update:
summary: Update an existing agent
value:
id: 1
name: Customer Support Agent v2
stage: released
responses:
'200':
description: Agent created or updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Agent'
examples:
success:
value:
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'
'400':
description: Bad request - validation error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
validation:
value:
error: Validation Error
details:
- message: Required
path:
- name
reservedSlug:
value:
error: Email slug "admin" is reserved and cannot be used
duplicateSlug:
value:
error: >-
Email slug "support-bot" is already in use by another
agent
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
Agent:
type: object
required:
- id
- name
- stage
- showInChat
- createdAt
- updatedAt
properties:
id:
type: integer
description: Unique agent identifier
example: 1
name:
type: string
description: Agent name
example: Customer Support Agent
description:
type: string
nullable: true
description: Short description of the agent's purpose
example: Handles customer inquiries and support tickets
logoUrl:
type: string
nullable: true
description: URL to the agent's logo image
conversationStarters:
type: array
nullable: true
description: Suggested conversation starters shown to users
items:
type: string
example:
- How can I help you today?
- What issue are you experiencing?
model:
type: string
nullable: true
description: Model identifier (e.g., `openai:gpt-4o`)
example: openai:gpt-4o
maxToolRoundtrips:
type: integer
nullable: true
description: Maximum number of tool call roundtrips per response
example: 50
systemPrompt:
type: string
nullable: true
description: System prompt / instructions for the agent
tools:
type: object
nullable: true
description: Tool definitions keyed by tool name
additionalProperties: true
mcpServers:
type: array
nullable: true
description: Connected MCP server IDs (integer mcp_server.id values)
items:
type: integer
stage:
type: string
description: Agent lifecycle stage
enum:
- development
- released
example: development
showInChat:
type: boolean
description: Whether the agent appears in the chat interface
example: true
emailSlug:
type: string
nullable: true
description: Custom email slug for the agent's email address
example: support-bot
publishedVersionId:
type: integer
nullable: true
description: |
ID of the `agent_version` snapshot this agent's config currently
reflects. Every save appends a version and advances this pointer;
see `GET /agents/versions`. The live agent fields above remain the
source of truth — this is bookkeeping for history and rollback.
example: 42
createdAt:
type: string
format: date-time
description: When the agent was created
example: '2024-01-15T10:30:00.000Z'
updatedAt:
type: string
format: date-time
description: When the agent was last updated
example: '2024-01-20T14:00:00.000Z'
tags:
type: array
description: Tags associated with this agent
items:
type: object
properties:
id:
type: integer
example: 1
name:
type: string
example: Production
Error:
type: object
required:
- error
properties:
error:
type: string
example: Bad Request
details:
type: array
items:
type: object
additionalProperties: true
responses:
Forbidden:
description: Forbidden - User is not an admin in the organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: 'Unauthorized: User is not an admin in this organization'
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Internal Server Error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
JWT token from Clerk authentication.
Must be from a user with `org:admin` role.
````