Agents
API endpoints for Agents
GET
/api/agents List lists agents for the user's active workspace.
Returns all agents the user has access to in their active workspace. Owners and admins see all agents, members only see assigned agents. Returns 401 if not authenticated, 200 OK with empty array if no active workspace, 500 on internal error, 200 OK with agents on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 401 | Authentication required |
| 500 | Internal server error |
Success
Response
Paginated response with data wrapped in a top-level 'data' key and pagination metadata in 'meta'
| Property | Type | Description |
|---|---|---|
| data.data[].id | integer (int64) | Unique agent identifier |
| data.data[].workspace_id | integer (int64) | ID of workspace that owns this agent |
| data.data[].name | string | Agent's display name |
| data.data[].description | string | null | Description of agent's purpose and capabilities |
| data.data[].status | string | Agent status: active, draft, published, or archived |
| data.data[].color | string | Hex color code for agent UI theming |
| data.data[].avatar | string | null | URL to agent's avatar image |
| data.data[].created_at | string (date-time) | Timestamp when agent was created |
| data.data[].updated_at | string (date-time) | Timestamp when agent was last updated |
| meta.current_page | integer | Current page number (1-indexed) |
| meta.last_page | integer | Last page number |
| meta.per_page | integer | Number of items per page |
| meta.total | integer (int64) | Total number of items across all pages |
POST
/api/agents Create creates a new agent.
Validates the request payload, checks workspace agent limits, and creates the agent with default LLM/embedding integrations from the workspace. Returns 400 if validation fails or name missing, 403 if agent limit exceeded, 500 on internal error, 201 with the new agent on success.
Request Body request.Agent
Agent
| Property | Type | Description |
|---|---|---|
| name | string | null | The agent's display name |
| description | string | null | A brief description of the agent's purpose and capabilities |
| status | "active" | "draft" | "published" | "archived" | Agent status: active, draft, published, or archived |
| color | string | null | Hex color code for agent UI theming (e.g., #FF5733) |
| avatar | string | null | URL to agent's avatar image (can be set directly or via base64 upload) |
| avatar_base64 | string | null | Base64-encoded avatar image for upload (png, jpg, gif, webp) |
| avatar_filename | string | null | Original filename for avatar upload |
| system_prompt | string | null | System instructions that define the agent's personality and behavior |
| instruction_template | string | null | Template for formatting user instructions before sending to LLM |
| llm_integration_id | integer (int64) | null | ID of the LLM integration to use (e.g., OpenAI, Anthropic) |
| llm_config | object | Configuration for LLM provider (temperature, max_tokens, etc.) |
| storage_integration_id | integer (int64) | null | ID of the vector storage integration for RAG |
| storage_config | object | Configuration for vector storage provider |
| contact_config | object | Configuration for contact capture forms displayed to visitors |
Response Codes
| Status Code | Description |
|---|---|
| 201 | Resource created successfully |
| 400 | Invalid request |
| 500 | Internal server error |
Resource created successfully
Response response.AgentResponse
Agent
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique agent identifier |
| workspace_id | integer (int64) | ID of workspace that owns this agent |
| name | string | Agent's display name |
| description | string | null | Description of agent's purpose and capabilities |
| status | string | Agent status: active, draft, published, or archived |
| color | string | Hex color code for agent UI theming |
| avatar | string | null | URL to agent's avatar image |
| system_prompt | string | null | System instructions that define agent's personality and behavior |
| instruction_template | string | null | Template for formatting user instructions |
| llm_integration_id | integer (int64) | null | ID of the LLM integration to use |
| llm_config | object | Configuration for LLM provider (temperature, max_tokens, etc.) |
| storage_integration_id | integer (int64) | null | ID of the vector storage integration for RAG |
| storage_config | object | Configuration for vector storage provider |
| health_status | object | Detailed health check results by capability |
| healthy | boolean | null | Overall health status (true if all capabilities healthy) |
| health_checked_at | string (date-time) | null | Timestamp of last health check |
| contact_config | object | Configuration for contact capture forms |
| created_at | string (date-time) | Timestamp when agent was created |
| updated_at | string (date-time) | Timestamp when agent was last updated |
GET
/api/agents/{agent_id} Get retrieves an agent.
Returns a single agent by ID with its integrations loaded. Returns 404 if agent not found, 500 on internal error, 200 OK with agent details on success.
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 404 | Resource not found |
| 500 | Internal server error |
Success
Response response.AgentResponse
Agent
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique agent identifier |
| workspace_id | integer (int64) | ID of workspace that owns this agent |
| name | string | Agent's display name |
| description | string | null | Description of agent's purpose and capabilities |
| status | string | Agent status: active, draft, published, or archived |
| color | string | Hex color code for agent UI theming |
| avatar | string | null | URL to agent's avatar image |
| system_prompt | string | null | System instructions that define agent's personality and behavior |
| instruction_template | string | null | Template for formatting user instructions |
| llm_integration_id | integer (int64) | null | ID of the LLM integration to use |
| llm_config | object | Configuration for LLM provider (temperature, max_tokens, etc.) |
| storage_integration_id | integer (int64) | null | ID of the vector storage integration for RAG |
| storage_config | object | Configuration for vector storage provider |
| health_status | object | Detailed health check results by capability |
| healthy | boolean | null | Overall health status (true if all capabilities healthy) |
| health_checked_at | string (date-time) | null | Timestamp of last health check |
| contact_config | object | Configuration for contact capture forms |
| created_at | string (date-time) | Timestamp when agent was created |
| updated_at | string (date-time) | Timestamp when agent was last updated |
PATCH
/api/agents/{agent_id} Update updates an agent.
Updates an existing agent with the provided fields. Uses PATCH semantics where nil fields are not changed. Returns 404 if agent not found, 400 for validation errors, 500 on internal error, 200 OK with updated agent on success.
Request Body request.Agent
Agent
| Property | Type | Description |
|---|---|---|
| name | string | null | The agent's display name |
| description | string | null | A brief description of the agent's purpose and capabilities |
| status | "active" | "draft" | "published" | "archived" | Agent status: active, draft, published, or archived |
| color | string | null | Hex color code for agent UI theming (e.g., #FF5733) |
| avatar | string | null | URL to agent's avatar image (can be set directly or via base64 upload) |
| avatar_base64 | string | null | Base64-encoded avatar image for upload (png, jpg, gif, webp) |
| avatar_filename | string | null | Original filename for avatar upload |
| system_prompt | string | null | System instructions that define the agent's personality and behavior |
| instruction_template | string | null | Template for formatting user instructions before sending to LLM |
| llm_integration_id | integer (int64) | null | ID of the LLM integration to use (e.g., OpenAI, Anthropic) |
| llm_config | object | Configuration for LLM provider (temperature, max_tokens, etc.) |
| storage_integration_id | integer (int64) | null | ID of the vector storage integration for RAG |
| storage_config | object | Configuration for vector storage provider |
| contact_config | object | Configuration for contact capture forms displayed to visitors |
Response Codes
| Status Code | Description |
|---|---|
| 200 | Success |
| 400 | Invalid request |
| 404 | Resource not found |
| 500 | Internal server error |
Success
Response response.AgentResponse
Agent
| Property | Type | Description |
|---|---|---|
| id | integer (int64) | Unique agent identifier |
| workspace_id | integer (int64) | ID of workspace that owns this agent |
| name | string | Agent's display name |
| description | string | null | Description of agent's purpose and capabilities |
| status | string | Agent status: active, draft, published, or archived |
| color | string | Hex color code for agent UI theming |
| avatar | string | null | URL to agent's avatar image |
| system_prompt | string | null | System instructions that define agent's personality and behavior |
| instruction_template | string | null | Template for formatting user instructions |
| llm_integration_id | integer (int64) | null | ID of the LLM integration to use |
| llm_config | object | Configuration for LLM provider (temperature, max_tokens, etc.) |
| storage_integration_id | integer (int64) | null | ID of the vector storage integration for RAG |
| storage_config | object | Configuration for vector storage provider |
| health_status | object | Detailed health check results by capability |
| healthy | boolean | null | Overall health status (true if all capabilities healthy) |
| health_checked_at | string (date-time) | null | Timestamp of last health check |
| contact_config | object | Configuration for contact capture forms |
| created_at | string (date-time) | Timestamp when agent was created |
| updated_at | string (date-time) | Timestamp when agent was last updated |
DELETE
/api/agents/{agent_id} Delete deletes an agent.
Soft deletes an agent by ID. Returns 404 if agent not found, 500 on internal error, 204 No Content on success.
Response Codes
| Status Code | Description |
|---|---|
| 204 | Success with no content |
| 404 | Resource not found |
| 500 | Internal server error |