API の規約

認証、ページング、エラー、冪等性。

Core API は https://api.us.cloud.subako.ai にあり、すべてのルートは /v1 の下にあります。API リファレンスにはすべてのエンドポイントの一覧と、実際のサーバーを呼び出せるプレイグラウンドがあります。

認証

すべての呼び出しで Authorization: Bearer <token> を送ります。トークンの種類はプレフィックスでわかります。

プレフィックス		有効期間
`sbk_ak_`	API key。1 つの Workspace で、与えられた権限を持ちます	無効化されるか、有効期限が来るまで
`sbk_st_`	Session token。1 つの Session だけに使えます	1 時間
`sbk_at_`	人のアクセストークン。`subako login` の後に CLI が保持します	数分。`subako token` で新しいものを出力できます

人は複数の Workspace に所属できるので、人のトークンを使う呼び出しでは、操作対象の Workspace の ID を Kikuvi-Workspace で指定します。

curl https://api.us.cloud.subako.ai/v1/agents \
  -H "Authorization: Bearer $(subako token | jq -r .access_token)" \
  -H "Kikuvi-Workspace: $WORKSPACE_ID"

この Header は、Workspace 単位のコレクション (/v1/agents、/v1/sessions、/v1/skills、/v1/functions、/v1/vaults、/v1/model-providers、/v1/api-keys) で必須です。リソースを ID で指定するルートでは、そのリソースから Workspace が決まります。API key はもともと 1 つの Workspace に属しているので、Header は不要です。API key で別の Workspace を指定すると、呼び出しは拒否されます。

Workspace の ID は、コンソールの概要ページで確認できます。

ページネーション

一覧は { "items": [...], "next_cursor": ..., "prev_cursor": ... } の形で、新しいものから順に返します。

パラメーター
`limit`	1~200 で、既定は 50 です。範囲外の値は範囲内に丸められず、エラーになります。
`after`	次のページを取得するときに、前のページの `next_cursor` を指定します
`before`	前のページを取得するときに、`prev_cursor` を指定します
`order`	`desc` (既定) または `asc`

Session の Event は、カーソルではなくシーケンス番号でページングします。詳しくは Event のストリームを参照してください。

エラー

失敗した呼び出しは、すべて同じ形式で返されます。

{ "error": { "code": "not_found", "message": "session not found" } }

`code`	ステータス
`invalid_request`	400
`unauthorized`	401
`forbidden`	403。Plan の上限や Organization の Credit が理由で拒否された場合もこれになります
`not_found`	404
`conflict`	409
`precondition_failed`	412
`too_many_requests`	429
`internal`	500

code で分岐してください。message は人が読むためのもので、変わることがあります。

冪等性

何かを作成する呼び出しには、Idempotency-Key Header (1~255 文字) を付けられます。同じキーで再び呼び出すと、処理を二度行わずに、最初の呼び出しと同じ応答を Idempotency-Replayed: true 付きで返します。そのため、タイムアウト後に再試行しても安全です。同じキーで異なるボディを送ると競合になります。一度しか表示されないシークレット (新しい Session の Session token や新しい API key など) は、再送時には返されません。キーは少なくとも 7 日間保持されます。

API の規約

認証

Workspace の Header

ページネーション

エラー

冪等性