Overview

The Ability API is a REST API that allows external services to run Abilities (workflows). It supports asynchronous execution, SSE streaming, status lookup, and request cancellation.

• Base URL : {host}/api/ability

Authentication

All requests require the X-API-KEY header.

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

Endpoints

1. Run an Ability asynchronously

Runs an Ability asynchronously and returns a request_id (transaction_id) immediately. You can retrieve the result via the status API or receive it via a callback URL.

POST /api/ability/{api_endpoint}

Path Parameters

Headers

Request Body (multipart/form-data)

params_json schema

Send a JSON object that matches the Ability's input parameters.

json

{

"inputData": "Text to analyze.",

"option1": "value1",

"option2": 123

}

The fields inside params_json vary by Ability. Check the input spec for the specific Ability.

Response

• Status: 200 OK

• Body: Request ID (string)

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

Error Responses

Example

bash

curl -X POST "{host}/api/ability/my-ability"

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

-F 'params_json={"inputData": "Hello"}'

-F 'callback_url=https://my-service.com/webhook' -F 'debug=false'

2. Run an Ability with SSE streaming

Runs an Ability and receives each node's execution output in real time via Server-Sent Events.

POST /api/ability/{api_endpoint}/sse

Path Parameters

Headers

Request Body (multipart/form-data)

Response

• Content-Type: text/event-stream

• Each event is delivered in the following format:

{event_type}: {message}

event_type values

When the stream ends, the connection is closed.

Example

bash

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

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

-F 'params_json={"inputData": "Hello"}'

-F 'debug=false'

--no-buffer

JavaScript client example

javascript

const formData = new FormData();

formData.append('params_json', JSON.stringify({ inputData: 'Hello' }));

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

const response = await fetch(`${host}/api/ability/my-ability/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 chunk = decoder.decode(value);

// 형식: "{event_type}:\n{message}\n\n"

const [eventLine, ...messageLines] = chunk.trim().split('\n');

const eventType = eventLine.replace(':', '');

const message = messageLines.join('\n');

console.log(`[${eventType}]`, message);

}

3. Check request status / result

Checks the processing status and results of an asynchronous execution request.

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

• GET /api/ability/{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": null,

"status": "COMPLETED",

"failure_reason": null,

"results": {

"output": "Ability execution result"

},

"artifact_metadata_json": null,

"request_params_json": "{\"inputData\":\"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/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status"

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

4. Cancel a request

Cancels an in-progress asynchronous request.

DELETE /api/ability/{api_endpoint}/{request_id}

Path Parameters

Headers

Response

• Status: 200 OK

• Body: true (success) or an error

Error Responses

Example

bash

curl -X DELETE "{host}/api/ability/my-ability/a1b2c3d4-e5f6-7890-abcd-ef1234567890"

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

5. Cancel multiple requests

Cancels multiple asynchronous requests at once.

DELETE /api/ability/{api_endpoint}?request_ids={id1}&request_ids={id2}

Path Parameters

Query Parameters

Headers

Response

• Status: 200 OK

• Body: true (success) or an error

Example

bash

curl -X DELETE "{host}/api/ability/my-ability?request_ids=id-001&request_ids=id-002&request_ids=id-003"

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

Common usage flows

Flow 1: Async execution + polling

• 1. POST /{api_endpoint} → Run Ability, get request_id

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

• 3. Check the result

Flow 2: Async execution + callback

• 1. POST /{api_endpoint} (with callback_url) → Run Ability

• 2. Receive results via POST to the callback URL

Flow 3: Real-time streaming

• 1. POST /{api_endpoint}/sse → Connect via SSE, receive node outputs in real time

• 2. Check the final result when the stream ends

Flow 4: Cancel a request

• 1. POST /{api_endpoint} → Run Ability, get request_id

• 2. DELETE /{api_endpoint}/{request_id} → Cancel a single request

  or

  DELETE /{api_endpoint}?request_ids=... → Cancel multiple requests