---
title: API の規約
description: 認証、ページング、エラー、冪等性。
---

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

## 認証

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

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

## Workspace の Header

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

```bash
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 のストリーム](/ja/build/streaming-events#ページ) を参照してください。

## エラー

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

```json
{ "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 日間保持されます。