ClouisleClouisle

Agent API

Manage AI agents, publish control, chat interaction, and statistics queries

Endpoint Overview

The Agent API provides agent lifecycle management, chat interaction, and statistics query capabilities. Base path: /api/v1/agents.

MethodPathPurpose
GET/api/v1/agentsList agents accessible to the current user
POST/api/v1/agentsCreate a new agent
GET/api/v1/agents/{agent_id}Get agent details (including full configuration)
PUT/api/v1/agents/{agent_id}Update agent configuration
DELETE/api/v1/agents/{agent_id}Permanently delete an agent
POST/api/v1/agents/{agent_id}/publishPublish an agent
POST/api/v1/agents/{agent_id}/unpublishUnpublish an agent
GET/api/v1/agents/{agent_id}/publicGet public agent basic info, authentication optional
POST/api/v1/agents/{agent_id}/chatNon-streaming chat
POST/api/v1/agents/{agent_id}/chat/streamSSE streaming chat
POST/api/v1/agents/{agent_id}/messages/{message_id}/regenerateRegenerate
POST/api/v1/agents/{agent_id}/messages/{message_id}/edit/streamEdit a user message and create a branch
GET/api/v1/agents/{agent_id}/messages/{message_id}/versionsQuery message versions
POST/api/v1/agents/{agent_id}/messages/{message_id}/switch-versionSwitch version
GET/api/v1/agents/{agent_id}/statsQuery agent statistics overview
GET/api/v1/agents/{agent_id}/stats/trendsQuery trend data
GET/api/v1/agents/{agent_id}/stats/tool-usageQuery tool usage statistics
GET/api/v1/agents/{agent_id}/stats/recent-conversationsQuery recent conversations

Authentication

All endpoints require an authenticated JWT user session. Chat endpoints additionally support API Keys (with bound agent permissions).

Required scopes:

ScopePurpose
agent:readList and view agents
agent:createCreate agents
agent:updateUpdate agents
agent:deleteDelete agents
agent:publishPublish or unpublish agents
agent:chatChat with agents

List Agents

GET /api/v1/agents

Get all agents accessible to the current user, with pagination, team filtering, status filtering, and keyword search.

Query Parameters

ParameterTypeRequiredDefaultDescription
pageintegerNo1Page number
page_sizeintegerNo20Items per page
team_idstringNo-Filter by team UUID
statusstringNo-Filter by status: draft, published
visibilitystringNo-Filter by visibility: private, team, public (legacy compatibility value)
keywordstringNo-Search by name or description
own_onlybooleanNofalseOnly show agents created by the current user

Request Example

curl -X GET "https://your-domain.com/api/v1/agents?page=1&page_size=20" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Fields

FieldTypeDescription
idstringAgent UUID
namestringName
descriptionstringDescription
iconstringIcon emoji or URL
avatar_urlstringAvatar URL
teamobjectTeam info (id, name, avatar_url)
modelobjectModel info (id, name, provider, model_id), null if unset
statusstringdraft or published
visibilitystringprivate or team
conversation_countintegerNumber of conversations
message_countintegerNumber of messages
created_byobjectCreator info (id, username, avatar_url)
created_atstringISO 8601 timestamp
updated_atstringISO 8601 timestamp

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "items": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "Customer Support Agent",
        "description": "Helps customers with common questions",
        "icon": "🤖",
        "avatar_url": "https://example.com/avatar.png",
        "team": {
          "id": "team-123",
          "name": "Support Team",
          "avatar_url": "https://example.com/team.png"
        },
        "model": {
          "id": "model-456",
          "name": "GPT-4",
          "provider": "openai",
          "provider_display_name": "OpenAI",
          "model_id": "gpt-4"
        },
        "status": "published",
        "visibility": "team",
        "conversation_count": 156,
        "message_count": 1234,
        "created_by": {
          "id": "user-001",
          "username": "alice",
          "avatar_url": "https://example.com/avatars/alice.jpg"
        },
        "created_at": "2026-02-11T10:00:00Z",
        "updated_at": "2026-02-11T15:30:00Z"
      }
    ],
    "total": 42,
    "page": 1,
    "page_size": 20
  },
  "msg": "success"
}

Get Agent Details

GET /api/v1/agents/{agent_id}

Get the complete configuration of a specified agent, including system prompt, tool configuration, knowledge base associations, and RAG parameters.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Example

curl -X GET "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response Fields

In addition to the list fields above, the details endpoint returns the full configuration:

FieldTypeDescription
model_idstringTeam model UUID
system_promptstringSystem prompt
max_iterationsintegerMax tool call iterations (1–200, default 5)
hide_tool_callsbooleanHide tool call details in chat UI
hide_message_actionsbooleanHide token usage/speed stats
hide_reasoningbooleanHide reasoning/chain-of-thought
tools_configarrayTool configs (type/name/tool_id/server_id/skill_id/config)
enable_attachmentsbooleanEnable file and image attachments
enable_user_input_requestbooleanEnable model-callable ask_user tool
enable_memorybooleanEnable cross-conversation memory
rag_modestringRAG mode: off, auto, agentic (default)
variablesarrayChat input variable definitions
knowledge_basesarrayAssociated knowledge base configs (with retrieval_top_k, score_threshold, search_mode)

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "system_prompt": "You are a helpful customer support agent...",
    "max_iterations": 5,
    "hide_tool_calls": false,
    "tools_config": [
      {
        "type": "builtin",
        "name": "web_search"
      }
    ],
    "enable_memory": false,
    "rag_mode": "agentic",
    "knowledge_bases": [
      {
        "id": "kb-assoc-001",
        "knowledge_base": {
          "id": "kb-789",
          "name": "Product Documentation",
          "description": "Product docs and FAQs",
          "icon": "📚",
          "document_count": 156
        },
        "retrieval_top_k": 5,
        "score_threshold": 0.3,
        "search_mode": "hybrid"
      }
    ],
    "status": "published",
    "visibility": "team",
    "created_at": "2026-02-11T10:00:00Z",
    "updated_at": "2026-02-11T15:30:00Z"
  },
  "msg": "success"
}

Error Response (404 Not Found)

{
  "code": 6200,
  "data": {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "msg": "Agent not found"
}

Create Agent

POST /api/v1/agents

Create a new AI agent. The agent is in draft status by default and must be published before it can be used for chat.

Request Body

{
  "name": "Customer Support Agent",
  "description": "Helps customers with common questions",
  "avatar_url": "https://example.com/avatar.png",
  "team_id": "team-123",
  "model_id": "model-456",
  "system_prompt": "You are a helpful customer support agent...",
  "max_iterations": 5,
  "hide_tool_calls": false,
  "tools_config": [
    {
      "type": "builtin",
      "name": "web_search"
    }
  ],
  "enable_memory": false,
  "rag_mode": "agentic",
  "knowledge_base_configs": [
    {
      "knowledge_base_id": "kb-789",
      "retrieval_top_k": 5,
      "score_threshold": 0.3,
      "search_mode": "hybrid"
    }
  ],
  "visibility": "team"
}

Request Fields

FieldTypeRequiredDescription
namestringYesName (max 100 chars)
descriptionstringNoDescription (max 500 chars)
iconstringNoIcon emoji or URL (max 500 chars)
avatar_urlstringNoAvatar URL
team_idstringYesTeam UUID
model_idstringNoTeam model UUID; uses team default if unset
system_promptstringNoSystem prompt/instructions
max_iterationsintegerNoMax tool call iterations (1–200, default 5)
hide_tool_callsbooleanNoHide tool call details in chat UI (default false)
hide_message_actionsbooleanNoHide token usage/speed stats (default false)
hide_reasoningbooleanNoHide reasoning/chain-of-thought (default false)
tools_configarrayNoTool configs (type/name/tool_id/server_id/skill_id/config)
tools_credentialsobjectNoTool credentials (API keys, tokens, etc.)
enable_attachmentsbooleanNoEnable file and image attachments (default false)
attachment_configobjectNoAttachment limits configuration
enable_user_input_requestbooleanNoEnable ask_user tool (default false)
enable_memorybooleanNoEnable cross-conversation memory (default false)
memory_configobjectNoMemory configuration
context_compression_configobjectNoContext compression configuration
enable_image_generationbooleanNoEnable image generation tool (default false)
image_generation_configobjectNoImage generation configuration
enable_video_generationbooleanNoEnable video generation tool (default false)
video_generation_configobjectNoVideo generation configuration
rag_modestringNoRAG mode: off, auto, agentic (default agentic)
knowledge_base_configsarrayNoKB configs (knowledge_base_id, retrieval_top_k, score_threshold, search_mode)
variablesarrayNoChat input variable definitions
opening_messagestringNoOpening message shown in chat
suggested_questionsarrayNoSuggested questions
visibilitystringNoprivate or team (default team)

Request Example

curl -X POST "https://your-domain.com/api/v1/agents" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "team_id": "team-123",
    "model_id": "model-456",
    "system_prompt": "You are a helpful customer support agent...",
    "tools_config": [{"type": "builtin", "name": "web_search"}],
    "knowledge_base_configs": [
      {
        "knowledge_base_id": "kb-789",
        "retrieval_top_k": 5,
        "score_threshold": 0.3,
        "search_mode": "hybrid"
      }
    ],
    "rag_mode": "agentic"
  }'

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Customer Support Agent",
    "description": "Helps customers with common questions",
    "status": "draft",
    "visibility": "team",
    "team": {
      "id": "team-123",
      "name": "Support Team",
      "avatar_url": null
    },
    "model_id": "model-456",
    "model": {
      "id": "model-456",
      "name": "GPT-4",
      "provider": "openai",
      "provider_display_name": "OpenAI",
      "model_id": "gpt-4"
    },
    "created_at": "2026-02-11T10:00:00Z",
    "created_by": {
      "id": "user-001",
      "username": "alice",
      "avatar_url": null
    }
  },
  "msg": "Agent created successfully"
}

Error Response (1001 Validation Error)

{
  "code": 1001,
  "data": {
    "errors": [
      {
        "field": "name",
        "message": "Name is required"
      },
      {
        "field": "model_id",
        "message": "Invalid model ID"
      }
    ]
  },
  "msg": "Validation failed"
}

After creation, the agent is in draft status. Call the publish endpoint to make it available for chat.

Update Agent

PUT /api/v1/agents/{agent_id}

Update the configuration of an existing agent. All fields are optional; only include the fields you want to update.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Body

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "system_prompt": "Updated system prompt...",
  "max_iterations": 8,
  "tools_config": [
    {"type": "builtin", "name": "web_search"},
    {"type": "builtin", "name": "code_interpreter"}
  ],
  "rag_mode": "auto"
}

Request Example

curl -X PUT "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Agent Name",
    "max_iterations": 8
  }'

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Updated Agent Name",
    "max_iterations": 8,
    "updated_at": "2026-02-11T16:00:00Z"
  },
  "msg": "Agent updated successfully"
}

Delete Agent

DELETE /api/v1/agents/{agent_id}

Permanently delete the specified agent. This action cannot be undone.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Example

curl -X DELETE "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200 OK)

{
  "code": 0,
  "data": null,
  "msg": "Agent deleted successfully"
}

Error Response (6200 Not Found)

{
  "code": 6200,
  "data": {
    "agent_id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "msg": "Agent not found"
}

Publish Agent

POST /api/v1/agents/{agent_id}/publish

Set the agent status to published, making it available for chat. The publish operation does not validate whether a model is configured (model validation occurs in subsequent chat/access paths with error code 6202).

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Example

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/publish" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "published"
  },
  "msg": "Agent published successfully"
}

The publish endpoint only sets the status and does not validate the model. If the agent is in draft status during a subsequent chat, 6202 Agent not published will be returned.

Unpublish Agent

POST /api/v1/agents/{agent_id}/unpublish

Set the agent status to draft, making it unavailable for chat.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Example

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/unpublish" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "draft"
  },
  "msg": "Agent unpublished successfully"
}

Chat (Non-Streaming)

POST /api/v1/agents/{agent_id}/chat

Send a message to the agent and synchronously receive the complete response. Suitable for short responses; for long tasks, use the SSE streaming endpoint.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Request Body

{
  "message": "What are your business hours?",
  "conversation_id": "conv-123",
  "files": [
    {
      "name": "document.pdf",
      "url": "https://example.com/document.pdf",
      "type": "application/pdf"
    }
  ],
  "file_urls": [
    {
      "asset_id": "asset-456",
      "url": "https://your-domain.com/api/v1/upload/files/asset-456",
      "filename": "report.pdf"
    }
  ],
  "variables": {
    "customer_tier": "premium"
  }
}

Request Fields

FieldTypeRequiredDescription
messagestringYesUser message (max 32000 chars)
imagesarrayNoImages for vision (name, url, type)
filesarrayNoParsed files (deprecated, use file_urls)
file_urlsarrayNoRaw uploaded asset metadata (asset_id, url, filename)
conversation_idstringNoConversation UUID; creates a new one if not provided
variablesobjectNoVariable values for the chat input form
history_overridearrayNoOverride conversation history (used for version switching/regeneration)

Request Example

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/chat" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "conversation_id": "conv-123"
  }'

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "conversation_id": "conv-123",
    "message": {
      "id": "msg-456",
      "conversation_id": "conv-123",
      "role": "assistant",
      "content": "Our business hours are Monday-Friday, 9 AM to 5 PM EST.",
      "tool_calls": [],
      "tool_name": null,
      "model_used": "gpt-4",
      "token_usage": {
        "prompt": 150,
        "completion": 25,
        "total": 175
      },
      "duration_ms": 2300,
      "rag_context": [
        {
          "document_id": "doc-789",
          "document_name": "Business Hours Policy",
          "chunk_id": "chunk-012",
          "content": "Business hours: Monday-Friday, 9 AM to 5 PM EST",
          "score": 0.95
        }
      ],
      "created_at": "2026-02-11T16:00:00Z",
      "version_number": 1,
      "version_count": 1
    },
    "usage": {
      "prompt": 150,
      "completion": 25,
      "total": 175
    }
  },
  "msg": "success"
}

Chat (Streaming)

POST /api/v1/agents/{agent_id}/chat/stream

Return the response as a stream via SSE (Server-Sent Events). The request body is the same as the non-streaming endpoint; there is no stream flag parameter.

Request Example

curl -X POST "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/chat/stream" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What are your business hours?",
    "conversation_id": "conv-123"
  }'

SSE Event Format

event: message_start
data: {"conversation_id": "conv-123", "message_id": "msg-456"}

event: content_delta
data: {"delta": "Our"}

event: content_delta
data: {"delta": " business"}

event: content_delta
data: {"delta": " hours"}

event: rag_context
data: {"contexts": [{"document_name": "FAQ", "content": "...", "score": 0.95}]}

event: message_end
data: {"usage": {"prompt_tokens": 150, "completion_tokens": 25, "total_tokens": 175}, "timing": {"first_token_ms": 320, "duration_ms": 2300, "tokens_per_second": 10.9}}
EventDescription
message_startMessage started, returns conversation_id and message_id
content_deltaIncremental text fragment
rag_contextRAG retrieval context (document name, content, relevance score)
message_endMessage ended, returns token usage and timing metrics

SSE clients need to parse the event stream as text/event-stream. See SSE Streaming Events for details.

Regenerate

POST /api/v1/agents/{agent_id}/messages/{message_id}/regenerate

Regenerate the response for a specified message. The request body structure is the same as the chat endpoint, and history_override can be used to adjust the historical context.

Edit Message and Create Branch

POST /api/v1/agents/{agent_id}/messages/{message_id}/edit/stream

Edit a user message and generate a branch response, returned as an SSE stream.

Query Message Versions

GET /api/v1/agents/{agent_id}/messages/{message_id}/versions

Query all versions of a specified message (including historical branches generated by regeneration and editing).

Switch Version

POST /api/v1/agents/{agent_id}/messages/{message_id}/switch-version

Switch to a specified version as the currently active message.

Agent Statistics

GET /api/v1/agents/{agent_id}/stats

Query the usage statistics overview of an agent within a specified time range.

Path Parameters

ParameterTypeRequiredDescription
agent_idstringYesAgent UUID

Query Parameters

ParameterTypeRequiredDefaultDescription
periodstringNo7dTime range: 24h, 7d, 30d, all

Request Example

curl -X GET "https://your-domain.com/api/v1/agents/550e8400-e29b-41d4-a716-446655440000/stats?period=30d" \
  -H "Authorization: Bearer YOUR_TOKEN"

Success Response (200 OK)

{
  "code": 0,
  "data": {
    "period": "30d",
    "overview": {
      "total_conversations": 156,
      "total_messages": 1234,
      "user_messages": 620,
      "assistant_messages": 610,
      "tool_messages": 4,
      "active_users": 23
    },
    "tokens": {
      "prompt_tokens": 250000,
      "completion_tokens": 206789,
      "total_tokens": 456789
    },
    "performance": {
      "avg_response_time_ms": 2300
    },
    "tools": {
      "tool_call_count": 512
    }
  },
  "msg": "success"
}

Other Statistics Endpoints

EndpointDescriptionParameters
GET /agents/{agent_id}/stats/trendsTrend dataperiod: 24h/7d/30d
GET /agents/{agent_id}/stats/tool-usageTool usage statisticsperiod: 24h/7d/30d/all
GET /agents/{agent_id}/stats/recent-conversationsRecent conversationslimit: default 10

Access Boundaries

  • The agent must be in published status to be used for chat.
  • The API Key must have the corresponding permissions; if the API Key is bound to a specific agent, it can only access agent IDs in the allowlist.
  • The agent's attachment limits, tool iteration caps, and model quotas still apply during API calls.

Error Codes

CodeMessageDescription
6200Agent not foundAgent does not exist
6201Access deniedCurrent user does not have access to the agent
6202Agent not publishedAgent is in draft status
3000Permission deniedInsufficient permissions
1001Validation failedInvalid request data
5104Duplicate nameAgent name is already taken

The current endpoints do not implement individual rate limiting; there is no rate-limit middleware.

  • API Get Started — Create an API Key, configure the base URL, and send your first request
  • Agent Chat — Send messages, attachments, variables, and consume streaming responses
  • SSE Streaming Events — Parse SSE events for agents and workflows
  • Error Handling — Recover by HTTP status and business error codes

How is this guide?

API Keys API

Manage API keys for authentication and access control

Agent Chat API

Send Agent messages and receive text, sources, tools, and media results

On this page

Endpoint OverviewAuthenticationList AgentsQuery ParametersRequest ExampleResponse FieldsSuccess Response (200 OK)Get Agent DetailsPath ParametersRequest ExampleResponse FieldsSuccess Response (200 OK)Error Response (404 Not Found)Create AgentRequest BodyRequest FieldsRequest ExampleSuccess Response (200 OK)Error Response (1001 Validation Error)Update AgentPath ParametersRequest BodyRequest ExampleSuccess Response (200 OK)Delete AgentPath ParametersRequest ExampleSuccess Response (200 OK)Error Response (6200 Not Found)Publish AgentPath ParametersRequest ExampleSuccess Response (200 OK)Unpublish AgentPath ParametersRequest ExampleSuccess Response (200 OK)Chat (Non-Streaming)Path ParametersRequest BodyRequest FieldsRequest ExampleSuccess Response (200 OK)Chat (Streaming)Request ExampleSSE Event FormatRegenerateEdit Message and Create BranchQuery Message VersionsSwitch VersionAgent StatisticsPath ParametersQuery ParametersRequest ExampleSuccess Response (200 OK)Other Statistics EndpointsAccess BoundariesError CodesRelated Documentation