Overview

Agent API is a REST API for interacting with agents from external services. It supports room creation/retrieval/deletion, asynchronous chat, and SSE (Server-Sent Events) streaming chat.

• Base URL: {host}/api/agent

Authentication

All requests require the X-API-KEY header.

X-API-KEY: your-api-key-here

If the API key is invalid or you don’t have permission, 403 Forbidden is returned.

Endpoints

1. Create a Chat Room

Create a chat room to talk with an agent.

POST /api/agent/{api_endpoint}/rooms

Path Parameters

Headers

Request Body

json

{

"user_ids": [1, 2]

}

Response

• Status: 200 OK

• Body: Created chat room UUID

json "e36644fa-0b2e-11f0-b130-143627ec67e9"

Error Responses

Example

bash

curl -X POST "{host}/api/agent/my-agent/rooms"

-H "X-API-KEY: your-api-key"

-H "Content-Type: application/json"

-d '{"user_ids": [1]}'

2. Get a Chat Room

Retrieve detailed information for a specific chat room.

GET /api/agent/{api_endpoint}/rooms/{chat_room_id}

Path Parameters

Headers

Response

• Status: 200 OK

• Body:

json

{

"id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"participants_json": {

"users": {

"1": {

"id": 1,

"type": "USER",

"joined_time": "2026-01-15T10:30:00",

"name": null

}

},

"agents": {

"42": {

"id": 42,

"type": "AGENT",

"joined_time": "2026-01-15T10:30:00",

"name": "My Agent"

}

}

},

"creator_id": 1,

"properties_json": {},

"created_time": "2026-01-15T10:30:00",

"updated_time": "2026-01-15T10:30:00"

}

Error Responses

Example

bash

curl -X GET "{host}/api/agent/my-agent/rooms/e36644fa-0b2e-11f0-b130-143627ec67e9"

-H "X-API-KEY: your-api-key”

3. Delete a Chat Room

Delete a chat room.

DELETE /api/agent/{api_endpoint}/rooms/{chat_room_id}

Path Parameters

Headers

Response

• Status: 200 OK

• Body: true (success) or false (failure)

Error Responses

| Status | Description |

|---|---|

| 403 Forbidden | API key is invalid or you don’t have access to the agent |

Example

bash

curl -X DELETE "{host}/api/agent/my-agent/rooms/e36644fa-0b2e-11f0-b130-143627ec67e9"

-H "X-API-KEY: your-api-key"

4. Send an Asynchronous Chat Request

Send a message to the agent and immediately receive a request_id. You can obtain the result via a separate status/result API or via a callback URL.

POST /api/agent/{api_endpoint}/async

Path Parameters

| Parameter | Type | Description |

|---|---|---|

| api_endpoint | string | Agent code |

Headers

Request Body (multipart/form-data)

params_json Structure

json

{

"input_message": "Hello",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"input_files": [

"https://example.com/image1.jpg",

"s3://bucket-name/image2.jpg"

]

}

Response

• Status: 200 OK

• Body: Request ID (string)

json "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

Error Responses

Example

bash

# Send text only

curl -X POST "{host}/api/agent/my-agent/async"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "Hello", "chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9"}'

-F 'debug=false'

# Send with files

curl -X POST "{host}/api/agent/my-agent/async"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "Analyze this image"}'

-F 'callback_url=https://my-service.com/webhook' -F 'files=@/path/to/image.png'

5. Get Async Request Status/Result

Check the processing status and results of an asynchronous chat request.

• GET /api/agent/{api_endpoint}/{request_id}/status

• GET /api/agent/{api_endpoint}/{request_id}/result

Both endpoints return the same response.

Path Parameters

Headers

Response

• Status: 200 OK

• Body:

json

{

"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"status": "COMPLETED",

"failure_reason": null,

"results": {

"output": "Agent response content"

},

"artifact_metadata_json": null,

"request_params_json": "{\"method\":\"POST\",\"client\":\"127.0.0.1\",\"params\":[{\"type\":\"text\",\"text\":\"Hello\"}]}",

"result_metadata_json": null,

"requested_time": "2026-01-15T10:30:00",

"updated_time": "2026-01-15T10:31:00"

}

Status Values

Example

bash

curl -X GET "{host}/api/agent/my-agent/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status"

-H "X-API-KEY: your-api-key"

6. SSE Streaming Chat

Perform real-time streaming chat with the agent. Receive the agent’s responses in real time via Server-Sent Events.

POST /api/agent/{api_endpoint}/sse

Path Parameters

Headers

Request Body (multipart/form-data)

params_json Structure

json

{

"input_message": "Hello",

"chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9",

"input_files": [

"https://example.com/image1.jpg"

]

}

Response

• Content-Type: text/event-stream

• Each event is delivered as JSON:

json {"ability_node_id": 1, "ability_node_name": "LLM Node", "results": {"output": "Response text..."}}

The connection closes when the stream ends.

Example

bash

curl -X POST "{host}/api/agent/my-agent/sse"

-H "X-API-KEY: your-api-key"

-F 'params_json={"input_message": "Hello", "chat_room_id": "e36644fa-0b2e-11f0-b130-143627ec67e9"}'

-F 'debug=false'

--no-buffer

JavaScript Client Example

javascript

const formData = new FormData();

formData.append('params_json', JSON.stringify({

input_message: 'Hello',

chat_room_id: 'e36644fa-0b2e-11f0-b130-143627ec67e9'

}));

formData.append('debug', 'false');

const response = await fetch(\$\{host\}/api/agent/my-agent/sse, {

method: 'POST',

headers: { 'X-API-KEY': 'your-api-key' },

body: formData

});

const reader = response.body.getReader();

const decoder = new TextDecoder();

while (true) {

const { done, value } = await reader.read();

if (done) break;

const text = decoder.decode(value);

const event = JSON.parse(text.trim());

console.log('Node:', event.ability_node_name, 'Result:', event.results);

}

Common Usage Flows

Flow 1: Async (Polling)

• 1. POST /{api_endpoint}/rooms → Create room, get room_id

• 2. POST /{api_endpoint}/async → Send message, get request_id

• 3. GET /{api_endpoint}/{request_id}/status → Poll status (until COMPLETED)

• 4. Check results, then repeat from step 2 as needed

Flow 2: Async (Callback)

• 1. POST /{api_endpoint}/rooms → Create room, get room_id

• 2. POST /{api_endpoint}/async → Send message with callback_url

• 3. Receive results at the callback URL (server receives a POST request)

Flow 3: Real-time Streaming

• 1. POST /{api_endpoint}/rooms → Create room, get room_id

• 2. POST /{api_endpoint}/sse → Connect to SSE, receive responses in real time

• 3. After the stream ends, repeat from step 2 as needed

Note: If you don’t specify chat_room_id, a chat room may be created automatically. To keep conversation history, use the same chat_room_id.