Skip to main content
The Agents API allows you to create, retrieve, update, delete, and manage AI agents, including their configurations, tools, actions, avatars, and version history.

​
Authentication

All endpoints require JWT authentication via the Authorization header: 
Authorization: Bearer <your_jwt_token>

​
Permissions

Agent operations require specific permissions:
  • VIEW: Read basic agent information
  • EDIT: Modify agent configuration
  • CREATE: Create new agents
  • DELETE: Remove agents
  • SHARE: Share agents with projects/groups

​
List Agents

curl -X GET "https://your-domain.com/api/agents?limit=20&page=1" \
  -H "Authorization: Bearer <token>"
Retrieve a paginated list of agents accessible to the authenticated user.

​
Query Parameters

​
limit
integer
default:"20"
Number of agents per page
​
page
integer
default:"1"
Page number
​
search
string
Search query for agent name or description
​
category
string
Filter by agent category

​
Response

​
agents
array
Array of agent objects
​
total
integer
Total number of agents
​
pages
integer
Total number of pages

​
Get Agent Categories

curl -X GET "https://your-domain.com/api/agents/categories" \
  -H "Authorization: Bearer <token>"
Retrieve all agent categories with counts.

​
Response

​
categories
array
Array of category objects with name and count

​
Get Agent (Basic Info)

curl -X GET "https://your-domain.com/api/agents/<agent_id>" \
  -H "Authorization: Bearer <token>"
Retrieve basic agent information (requires VIEW permission). Returns safe, non-sensitive data suitable for viewing purposes.

​
Path Parameters

​
id
string
required
The agent ID

​
Response

Returns an agent object with basic information excluding sensitive configuration details.

​
Get Agent (Full Details)

curl -X GET "https://your-domain.com/api/agents/<agent_id>/expanded" \
  -H "Authorization: Bearer <token>"
Retrieve complete agent details including sensitive configuration (requires EDIT permission). Returns full agent data for editing/configuration purposes.

​
Path Parameters

​
id
string
required
The agent ID

​
Response

​
id
string
Unique agent identifier
​
name
string
Agent name
​
description
string
Agent description
​
instructions
string
System instructions/prompt for the agent
​
model
string
Model identifier (e.g., “gpt-4”, “claude-3-opus”)
​
provider
string
Provider name (e.g., “openAI”, “anthropic”)
​
tools
array
Array of enabled tool configurations
​
tool_resources
object
Tool-specific resources like file_search file IDs
​
version
integer
Current version number
​
version_history
array
Array of previous versions

​
Create Agent

curl -X POST "https://your-domain.com/api/agents" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Assistant",
    "description": "Helps with research tasks",
    "instructions": "You are a helpful research assistant.",
    "model": "gpt-4",
    "provider": "openAI",
    "tools": ["web_search", "code_interpreter"]
  }'
Create a new agent (requires CREATE permission).

​
Request Body

​
name
string
required
Agent name (max 256 characters)
​
description
string
Agent description
​
instructions
string
System instructions/prompt for the agent
​
model
string
required
Model identifier
​
provider
string
required
Provider name (e.g., “openAI”, “anthropic”, “bedrock”)
​
tools
array
Array of tool identifiers to enable
​
tool_resources
object
Tool-specific resources
​
projectIds
array
Array of project IDs to share the agent with

​
Response

Returns the created agent object with status 201 Created.

​
Update Agent

curl -X PATCH "https://your-domain.com/api/agents/<agent_id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Research Assistant",
    "instructions": "Updated instructions"
  }'
Update an existing agent (requires EDIT permission).

​
Path Parameters

​
id
string
required
The agent ID

​
Request Body

Accepts partial agent updates. All fields are optional.
​
name
string
Updated agent name
​
description
string
Updated description
​
instructions
string
Updated instructions
​
model
string
Updated model
​
tools
array
Updated tools array
​
projectIds
array
Add agent to projects (requires SHARE permission)
​
removeProjectIds
array
Remove agent from projects (requires SHARE permission)

​
Response

Returns the updated agent object.

​
Duplicate Agent

curl -X POST "https://your-domain.com/api/agents/<agent_id>/duplicate" \
  -H "Authorization: Bearer <token>"
Create a duplicate of an existing agent (requires VIEW permission on source, CREATE permission to duplicate).

​
Path Parameters

​
id
string
required
The agent ID to duplicate

​
Response

Returns the newly created duplicate agent with status 201 Created.

​
Delete Agent

curl -X DELETE "https://your-domain.com/api/agents/<agent_id>" \
  -H "Authorization: Bearer <token>"
Delete an agent (requires DELETE permission).

​
Path Parameters

​
id
string
required
The agent ID to delete

​
Response

Returns the deleted agent object with status 200 OK.

​
Revert Agent Version

curl -X POST "https://your-domain.com/api/agents/<agent_id>/revert" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "version_index": 2
  }'
Revert an agent to a previous version (requires EDIT permission).

​
Path Parameters

​
id
string
required
The agent ID

​
Request Body

​
version_index
integer
required
Index of the version to revert to (0-based)

​
Response

Returns the agent object with the reverted configuration.

​
Upload Agent Avatar

curl -X POST "https://your-domain.com/api/files/images/agents/<agent_id>/avatar" \
  -H "Authorization: Bearer <token>" \
  -F "[email protected]" \
  -F "metadata={}"
Upload or update an avatar image for an agent (requires EDIT permission).

​
Path Parameters

​
agent_id
string
required
The agent ID

​
Request

Multipart form data with file and optional metadata.
​
file
file
required
Avatar image file (PNG, JPG, WEBP, GIF)
​
metadata
string
JSON string with optional metadata

​
Response

​
url
string
URL of the uploaded avatar

​
Get Available Tools

curl -X GET "https://your-domain.com/api/agents/tools" \
  -H "Authorization: Bearer <token>"
Retrieve a list of available tools that can be enabled for agents.

​
Response

​
tools
array
Array of tool definitions

​
Get Agent Actions

curl -X GET "https://your-domain.com/api/agents/actions" \
  -H "Authorization: Bearer <token>"
Retrieve custom actions (OpenAPI specs) available for agents.

​
Response

Returns an array of action definitions with OpenAPI specifications.

​
Common Error Codes

Status CodeDescription
400Bad Request - Invalid parameters or malformed request
401Unauthorized - Invalid or missing JWT token
403Forbidden - Insufficient permissions for the operation
404Not Found - Agent does not exist
500Internal Server Error - Server-side error occurred

Build docs developers (and LLMs) love

Get started for freeTalk to us