Ability API 연동 가이드

개요

Ability API는 외부 서비스에서 어빌리티(워크플로우)를 실행하기 위한 REST API입니다. 비동기 실행, SSE 스트리밍, 상태 조회, 요청 취소를 지원합니다.

• Base URL : {host}/api/ability

인증

모든 요청에 X-API-KEY 헤더가 필요합니다.

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

엔드포인트

1. 어빌리티 비동기 실행

어빌리티를 비동기로 실행하고 request_id(transaction_id)를 즉시 반환받습니다. 결과는 상태 조회 API 또는 콜백 URL로 받을 수 있습니다.

POST /api/ability/{api_endpoint}

Path Parameters

Headers

Request Body (multipart/form-data)

params_json 구조

어빌리티에 정의된 입력 파라미터에 맞는 JSON 객체를 전달합니다.

json

{

"inputData": "분석할 텍스트입니다.",

"option1": "value1",

"option2": 123

}

params_json의 필드는 어빌리티마다 다릅니다. 해당 어빌리티의 입력 스펙을 확인하세요.

Response

• Status: 200 OK

• Body: 요청 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": "안녕하세요"}'

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

-F 'debug=false'

2. 어빌리티 SSE 스트리밍 실행

어빌리티를 실행하며 Server-Sent Events를 통해 각 노드의 실행 결과를 실시간으로 수신합니다.

POST /api/ability/{api_endpoint}/sse

Path Parameters

Headers

Request Body (multipart/form-data)

Response

• Content-Type: text/event-stream

• 각 이벤트는 아래 형식으로 전달됩니다:

{event_type}: {message}

event_type 값

스트림이 종료되면 연결이 닫힙니다.

Example

bash

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

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

-F 'params_json={"inputData": "안녕하세요"}'

-F 'debug=false'

--no-buffer

JavaScript 클라이언트 예시

javascript

const formData = new FormData();

formData.append('params_json', JSON.stringify({ inputData: '안녕하세요' }));

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. 요청 상태/결과 조회

비동기 실행 요청의 처리 상태 및 결과를 조회합니다.

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

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

두 엔드포인트는 동일한 응답을 반환합니다.

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": "어빌리티 실행 결과"

},

"artifact_metadata_json": null,

"request_params_json": "{\"inputData\":\"안녕하세요\"}",

"result_metadata_json": null,

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

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

}

status 값

Example

bash

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

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

4. 요청 취소

진행 중인 비동기 요청을 취소합니다.

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

Path Parameters

Headers

Response

• Status: 200 OK

• Body: true (성공) 또는 에러

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. 요청 일괄 취소

여러 비동기 요청을 한 번에 취소합니다.

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

Path Parameters

Query Parameters

Headers

Response

• Status: 200 OK

• Body: true (성공) 또는 에러

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"

일반적인 사용 흐름

흐름 1: 비동기 실행 + Polling

• 1. POST /{api_endpoint} → 어빌리티 실행, request_id 획득

• 2. GET /{api_endpoint}/{request_id}/status → 상태 폴링 (COMPLETED가 될 때까지)

• 3. 결과 확인

흐름 2: 비동기 실행 + Callback

• 1. POST /{api_endpoint} (callback_url 포함) → 어빌리티 실행

• 2. 콜백 URL로 결과 수신 (서버에서 POST 요청)

흐름 3: 실시간 스트리밍

• 1. POST /{api_endpoint}/sse → SSE 연결, 실시간 노드 실행 결과 수신

• 2. 스트림 종료 시 최종 결과 확인

흐름 4: 요청 취소

• 1. POST /{api_endpoint} → 어빌리티 실행, request_id 획득

• 2. DELETE /{api_endpoint}/{request_id} → 개별 취소

  또는

  DELETE /{api_endpoint}?request_ids=... → 일괄 취소