概要

Ability API は、外部サービスから Abilities（ワークフロー）を実行するための REST API です。非同期実行、SSE ストリーミング、ステータス参照、リクエストのキャンセルに対応しています。

• Base URL：{host}/api/ability

認証

すべてのリクエストで X-API-KEY ヘッダーが必要です。

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

エンドポイント

1. Ability を非同期で実行

Ability を非同期で実行し、即座に request_id（transaction_id）を返します。結果はステータス API で取得するか、コールバック URL 経由で受け取れます。

POST /api/ability/{api_endpoint}

パスパラメータ

ヘッダー

リクエストボディ（multipart/form-data）

params_json スキーマ

Ability の入力パラメータに一致する JSON オブジェクトを送信します。

json

{

"inputData": "Text to analyze.",

"option1": "value1",

"option2": 123

}

params_json 内のフィールドは Ability ごとに異なります。対象 Ability の入力仕様を確認してください。

レスポンス

• Status：200 OK

• Body：Request ID（string）

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

エラーレスポンス

例

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. SSE ストリーミングで Ability を実行

Ability を実行し、各ノードの実行出力を Server-Sent Events でリアルタイムで受け取ります。

POST /api/ability/{api_endpoint}/sse

パスパラメータ

ヘッダー

リクエストボディ（multipart/form-data）

レスポンス

• Content-Type：text/event-stream

• 各イベントは次の形式で配信されます：

{event_type}: {message}

event_type の値

ストリームが終了すると、接続が自動的に閉じられます。

例

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 クライアント例

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);

// format: "{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

どちらのエンドポイントも同じレスポンスを返します。

パスパラメータ

ヘッダー

レスポンス

• 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 の値

例

bash

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

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

4. リクエストをキャンセル

処理中の非同期リクエストを1件キャンセルします。

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

パスパラメータ

ヘッダー

レスポンス

• Status：200 OK

• Body：true（成功）またはエラー

エラーレスポンス

例

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}

パスパラメータ

クエリパラメータ

ヘッダー

レスポンス

• Status：200 OK

• Body：true（成功）またはエラー

例

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：非同期実行＋ポーリング

• 1. POST /{api_endpoint} → Ability 実行、request_id を取得

• 2. GET /{api_endpoint}/{request_id}/status → ステータスをポーリング（COMPLETED まで）

• 3. 結果を確認

フロー2：非同期実行＋コールバック

• 1. POST /{api_endpoint}（callback_url 付き）→ Ability 実行

• 2. コールバック URL への POST で結果を受信

フロー3：リアルタイムストリーミング

• 1. POST /{api_endpoint}/sse → SSE 接続し、ノード出力をリアルタイム受信

• 2. ストリーム終了時に最終結果を確認

フロー4：リクエストをキャンセル

• 1. POST /{api_endpoint} → Ability 実行、request_id を取得

• 2. DELETE /{api_endpoint}/{request_id} → 単一キャンセル

  または

  DELETE /{api_endpoint}?request_ids=... → 複数キャンセル