API での Session

バックエンドで Session を作成し、ブラウザーに渡します。

コンソールは Core API のクライアントの 1 つにすぎず、皆さんのプロダクトも同じように Core API を使えます。よくある構成では、役割を次の 2 つに分けます:

• バックエンド は API key を持ち、ユーザーごとに Session を作成します。API key はバックエンドの外に出しません。
• ブラウザー のページは Session の Session token を受け取り、その Session の中の操作をすべて行います。メッセージの送信、Run の追跡、承認やフォームへの回答、ページ独自の Tool の提供などです。

いずれも https://api.us.cloud.subako.ai/v1 への普通の HTTP リクエストで、SDK はこれをラップしたものです。

Session を作成する

curl -X POST https://api.us.cloud.subako.ai/v1/sessions \
  -H "Authorization: Bearer $SUBAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ticket-4192-session" \
  -d '{
    "agent_id": "<agent-id>",
    "display_name": "ticket-4192",
    "vault_ids": ["<vault-id>"],
    "metadata": { "tenant_id": "t_123" }
  }'

API key には Session › 作成 の権限が必要です。レスポンスとして、最初の Session token を含む Session が返ります:

{
  "id": "01a0877f-d3b3-7e73-9eed-a16caee8cff7",
  "workspace_id": "01a0877c-03d9-7823-b997-f42147b8b607",
  "agent_id": "01a0877d-9a1f-7c40-8e2b-5b3c4d6e7f80",
  "agent_version_id": "01a0877e-1b2c-7d3e-9f40-a1b2c3d4e5f6",
  "display_name": "ticket-4192",
  "status": "idle",
  "session_token": "sbk_st_...",
  "session_token_expires_at": "2026-09-09T19:48:16Z",
  "metadata": { "tenant_id": "t_123" },
  "created_at": "2026-09-09T18:48:16Z"
}

同じ Idempotency-Key で再度送ると、Session は新たに作成されず、同じ Session が返ります。ただし、Session token は一度しか表示されないため、このレスポンスには含まれません。必要なら新しい Session token を発行してください。

Session token

Session token (sbk_st_…) は、それ自体には権限を持ちません。使えるのは 1 つの Session、つまり /v1/sessions/{その ID}/ 以下のルートだけです。Session の一覧取得や作成はできず、その Session の外にあるものは何も読めません。

Session token でできるのは、その Session の中での次の操作です。ログの読み取りと追跡、メッセージの送信、取り消し、承認の許可と拒否、フォームへの回答、Client の登録、Session の名前変更と削除、Volume の読み書き。

Session token の有効期限は 1 時間です。期限が切れる前に、バックエンドから次の Session token を発行してください:

curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/tokens \
  -H "Authorization: Bearer $SUBAKO_API_KEY"

これには Session › 管理 の権限が必要です。Session token で Session token を発行することはできません。

Session とやり取りする

# メッセージを送ります。Run を開始するか、実行中の Run に指示します。
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/events \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"type": "input", "text": "Summarize ticket 4192."}'
# {"run_id": "01a08780-...", "outcome": "new_run"}

# 実行中の Run を停止します。
curl -X POST https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID/cancel \
  -H "Authorization: Bearer $SUBAKO_SESSION_TOKEN"

Run の実行中に入力を送ると "outcome": "steered" が返り、その入力は Run の終了を待たずに実行中の Run に加わります。取り消しは協調的に行われ、Run は次のチェックポイントで止まって run_cancelled で終わります。

Session で起きていることは Event のストリーム で追えます。

ブラウザーから呼び出す

ページは Session token で API を呼び出します。その際ブラウザーは、ページの Origin からの呼び出しが許可されているかを事前に確認します。これが CORS です。許可する Origin は Agent ごとに、コンソールの Agent のページ (CORS › 編集)、subako agent set-security、または API で設定します:

curl -X PUT https://api.us.cloud.subako.ai/v1/agents/$AGENT_ID/security \
  -H "Authorization: Bearer $SUBAKO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"allowed_origins": ["https://app.acme.example"]}'

Origin は scheme://host[:port] の形式で書き、パスは含めません。* を指定するとすべての Origin を許可します。この設定が適用されるのは、その Agent の Session の /v1/sessions/{id}/ 以下のルートだけです。ページから Session を作成したり API key を使ったりすることはできないので、API key はサーバーの外に出ません。

ブラウザーの EventSource は Authorization Header を送れないため、ストリームは fetch で読んでください。TypeScript SDK もこの方法で読んでいます。

一覧の取得と後片付け

curl "https://api.us.cloud.subako.ai/v1/sessions?agent_id=$AGENT_ID&limit=20" \
  -H "Authorization: Bearer $SUBAKO_API_KEY"

curl -X DELETE https://api.us.cloud.subako.ai/v1/sessions/$SESSION_ID \
  -H "Authorization: Bearer $SUBAKO_API_KEY"

Session を削除すると、そのログと Volume も削除されます。記録済みの使用量は削除されずに残ります。

認証、Workspace の Header、ページネーション、エラー、冪等性については API の規約 を参照してください。