> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/api/ja/preparation/conventions.md).

# API 共通規約

MaiAgent プラットフォーム API を呼び出す際の共通ルール。URL とバージョンプレフィックス、API Key 認証、レート制限、エラーレスポンスとステータスコード、ページネーション、フィールド形式、アップロードサイズの上限を説明します

このページでは、すべてのプラットフォーム API に共通する URL、認証、レート制限、エラーレスポンス、ページネーション、フィールド形式、アップロード上限をまとめています。各エンドポイントのフィールドと例は、左側の「API エンドポイントドキュメント」を参照してください。このページのルールはすべてのエンドポイントに適用されるため、個別のページでは繰り返し説明していません。実装を始める前に一度お読みください。

{% hint style="info" %}

* API Key の作成と管理の画面操作は、ユーザーマニュアルの [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys)を参照してください。呼び出しログの確認は [API 呼び出しログ](https://docs.maiagent.ai/org/developer/api-logs)を参照してください。
* 初めて連携する際の手順は、技術者向けマニュアルの[クイックスタート](https://docs.maiagent.ai/tech/api-integration/quickstart)を参照してください。
  {% endhint %}

## URL とバージョンプレフィックス <a href="#base-url" id="base-url"></a>

SaaS の API URL は `https://api.maiagent.ai/api/v1/` です。オンプレミスやプライベートクラウドの環境では、自社のプラットフォームドメインに置き換えてください。

* `/api/` と `/api/v1/` は同じエンドポイント群を公開しており、パス、フィールド、権限はすべて同じです。
* AI Gateway（OpenAI 互換エンドポイント）と SCIM は **`/api/v1/` 配下でのみ**利用できます。
* 新しい連携では、必ず `/api/v1/` を使用してください。
* エンドポイントのパスは `/` で終わります。末尾の `/` がない場合は、`/` を追加した URL への `301` リダイレクトが返ります。一部の HTTP クライアントはリダイレクト時に `POST` を `GET` に変更するため、末尾に `/` がある URL を直接呼び出してください。

## 認証 <a href="#authentication" id="authentication"></a>

サーバー間の呼び出しでは、API Key を `Authorization` ヘッダーに指定します。

```
Authorization: Api-Key <ご自身の API Key>
```

キーは英数字のプレフィックスとシークレットの 2 つの部分で構成され、`.` で区切られています。必ず全体を指定してください。

| ルール                   | 説明                                                                                                                                                                               |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| キーは 1 人のメンバーに紐づきます    | 呼び出し先の組織はそのメンバーの所属組織になります。リクエストで組織 ID を別途指定する必要はありません                                                                                                                            |
| 権限はメンバーのロールと同じです      | エンドポイントごとのスコープはありません。メンバーが実行できる操作は、キーでも実行できます。権限が不足している場合は `403` が返ります。[API キーの権限範囲](https://docs.maiagent.ai/api/ja/preparation/authentication.md#api-key-permissions)を参照してください |
| メンバーを無効にするとキーも無効になります | メンバーが無効化されるか組織から削除されると、そのキーは直ちに使用できなくなります                                                                                                                                        |
| 有効期限切れ、無効化、取り消し       | 存在しないキーと同じく `401` が返り、レスポンスに理由は含まれません                                                                                                                                            |
| キー全体が表示されるのは一度だけです    | 作成後は一部の文字のみ表示されます。紛失した場合は新しいキーを作成してください                                                                                                                                          |

キーの作成と管理の入口は、[API 認証方式](https://docs.maiagent.ai/api/ja/preparation/authentication.md)を参照してください。

### 認証失敗時のレスポンス <a href="#auth-errors" id="auth-errors"></a>

キーが指定されていない場合、ヘッダーの形式が正しくない場合、またはキーが無効な場合（存在しない、有効期限切れ、無効化済み、取り消し済み、紐づくメンバーが無効化済みまたは組織から削除済み）は、いずれも `401` と同じ内容が返ります。

```json
{"detail": "Authentication credentials were not provided."}
```

* キーが無効な場合も「認証情報が提供されていない」というメッセージになります。プラットフォームは認識できないキーを認証情報の未指定として扱い、具体的な理由は示しません。
* レスポンスには `WWW-Authenticate` ヘッダーが含まれます。多くのエンドポイントでは値が `Bearer realm="api"` です（これらのエンドポイントは OAuth アクセストークンも受け付けます）。API Key のみを受け付けるエンドポイント（下記の `api-key-context` など）では `Api-Key` になります。認証失敗は `401` ステータスコードで判定し、このヘッダーの値で送信する認証情報の種類を決めないでください。
* API Key を `Bearer` の後に指定すると、プラットフォームはログイントークンとして検証し、`401` と異なる内容を返します。

```json
{"detail": "Given token not valid for any token type", "code": "token_not_valid", "messages": [ … ]}
```

このレスポンスを受け取った場合は、ヘッダーを `Api-Key <キー>` に変更してください。

{% hint style="warning" %}
**連携用キーの推奨設定**：連携専用のメンバーを作成し、必要なロール権限のみを付与したうえで、そのメンバーのキーを発行し、有効期限を設定してください。個人アカウントに紐づくキーは、その従業員の退職などでアカウントが無効化されると使用できなくなり、連携も中断します。API Key はサーバー側でのみ保持してください。プラットフォーム API は許可されたドメインからのクロスオリジン（CORS）呼び出しのみを許可しており、ブラウザーにキーを露出させるべきではありません。
{% endhint %}

### キーが所属する組織の確認 <a href="#api-key-context" id="api-key-context"></a>

自社のゲートウェイでキーの所属組織を事前に確認するには、`GET /api/v1/users/api-key-context/` を呼び出します。レスポンスは `{"organizationId": "…"}` です。このエンドポイントは API Key のみを受け付け、キーの RPM にはカウントされません。

### その他の認証情報 <a href="#other-credentials" id="other-credentials"></a>

MCP クライアントをメンバーとして接続する方法は、技術者向けマニュアルの [OAuth 認可サーバーとしての MaiAgent](https://docs.maiagent.ai/tech/identity-and-access/maiagent-oauth-server)を参照してください。自社システムに MaiGPT を埋め込むためのメンバートークンについては、[MaiGPT 連携：メンバー ID による埋め込み](https://docs.maiagent.ai/tech/work/maigpt-system-integration-guide/maigpt-integration#member-embed)を参照してください。

## レート制限 <a href="#rate-limits" id="rate-limits"></a>

プラットフォーム API には、**全体に適用されるデフォルトの上限はありません**。制限されるのは次の項目のみです。

| 対象                                                   | 上限                     | 集計方法                           | 変更できる担当者・設定箇所                                                                                                |
| ---------------------------------------------------- | ---------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
| API Key ごとのリクエスト数（RPM）                               | 管理者が設定します。未設定の場合は無制限です | キーごと、60 秒ごとです                  | 組織の <mark style="color:blue;">API Key 管理</mark>                                                              |
| AI Gateway のトークン数（TPM）                               | 管理者が設定します。未設定の場合は無制限です | キーごと、1 分ごとで、Gateway 推論のみを集計します | 同上です。[AI Gateway の制限](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible#limits)を参照してください |
| SCIM エンドポイント                                         | 100 回／分                | 組織ごとです                         | 固定です                                                                                                         |
| `web-chats/{id}/setup-contact-credentials/`          | 30 回／分                 | 送信元 IP ごとです                    | 固定です                                                                                                         |
| ログイン不要の料金照会（`credit/items/`、`credit/pricing-rules/`） | 60 回／分                 | 送信元 IP ごとです                    | 固定です                                                                                                         |
| `auth/login/`                                        | デフォルトで 10 回／分          | 送信元 IP ごとです                    | プラットフォームの設定です                                                                                                |
| 認証情報なしの Web Chat リクエスト（会話の継続、添付ファイルのアップロードなど）        | エンドポイントに応じて 10～30 回／分  | 送信元 IP ごとです                    | 固定です                                                                                                         |

* キーの RPM は AI Gateway だけでなく、そのキーで呼び出せるすべてのプラットフォーム API に適用されます。エンドポイント自体にも上限がある場合（表の固定上限など）、API Key による呼び出しには両方の制限が適用されます。それぞれ別々に集計され、先にいずれかの上限に達すると `429` が返ります。`Retry-After` は待機時間が長い方の値になります。例外は 2 つあります。[キーが所属する組織の確認](#api-key-context)のエンドポイントはキーの RPM にカウントされません。また、ログイン不要の料金照会（`credit/items/`、`credit/pricing-rules/`）は認証情報を認識しないため、API Key を付けても送信元 IP ごとの上限のみが適用され、キーの RPM にはカウントされません。
* OAuth アクセストークンや管理画面へのログインによるリクエストには、キーの RPM 制限は適用されません。
* 上限を超えると `429` が返り、`Retry-After` ヘッダーに秒数が含まれます。その秒数だけ待機してから再試行し、直ちに再送しないでください。

```json
{"detail": "Request was throttled. Expected available in 42 seconds."}
```

## エラーレスポンス <a href="#errors" id="errors"></a>

プラットフォーム API に統一されたエラーコード一覧はありません。エラー処理では **HTTP ステータスコード**で判定し、レスポンスに `code` がある場合はさらに `code` で分類してください。**`detail` の文字列を照合しないでください**。文字列は `Accept-Language` に応じて翻訳され、表現が変わる場合もあります。

### レスポンスの形式 <a href="#error-shapes" id="error-shapes"></a>

| 形式              | 例                                                                  | 主な用途                                                                         |
| --------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------- |
| `detail` オブジェクト | `{"detail": "You do not have permission to perform this action."}` | 認証、権限、対象なし、レート制限、プラン、Credits などです。一部では `code` やその他のフィールドも含まれます               |
| フィールドオブジェクト     | `{"name": ["This field is required."]}`                            | フィールドの検証エラーです。キーは camelCase のフィールド名で、単一フィールドに属さないエラーは `nonFieldErrors` に入ります |
| 文字列配列           | `["…"]`                                                            | 対応するフィールドのない一部の検証エラーです                                                       |

例外は次のとおりです。

* **AI Gateway** の OpenAI 互換エンドポイントは、OpenAI 形式の `error` オブジェクトを使用します。[AI Gateway のエラー形式](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible#errors)を参照してください。
* **SCIM** エンドポイントでは、リクエストボディのエラー、対象なし、競合に対し、SCIM 2.0 仕様に従ってレスポンスを返します（`schemas`、`status`、`detail`）。
* **存在しない URL**（パスの誤り、リソース ID の不足）では `404` が返り、内容は JSON ではなく HTML です。`5xx` レスポンスも JSON とは限りません。レスポンスを解析する前に `Content-Type` を確認してください。

### ステータスコード <a href="#status-codes" id="status-codes"></a>

| ステータスコード          | 意味                                                                                                                                                                             | 推奨する対処                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`／`201`／`204` | 成功です。`204` はレスポンスボディがなく、削除操作でよく使われます                                                                                                                                           | —                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `202`             | 未完了です。会話の返信（completions）で、その会話にまだ処理中の添付ファイルがある場合（`status: "pending_attachments"`）、または非ストリーミングの返信が待機上限を超えた場合（`status: "processing"`）に `202` が返ります。多くの場合メッセージは受理済みです。右列を参照してください | `processing`、または `messageCreated` が `true` の `pending_attachments` の場合：メッセージは受理済みのため、**再送しないでください**。`Location` で返信を照会するか、[Outgoing Webhook](https://docs.maiagent.ai/tech/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu#webhook-reply) に切り替えてください。`messageCreated` が `false` の場合：今回の内容は受理されていません。`Location` があれば先に前の質問の結果を取得し、なければ数秒おいて再送してください。完全な判断手順は [返信取得のフロー](https://docs.maiagent.ai/tech/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu#reply-flow)を参照してください |
| `301`             | パス末尾の `/` がありません                                                                                                                                                               | 末尾に `/` がある URL を使用してください                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `400`             | フィールドの検証エラーです。リソース ID が有効な UUID でない場合、多くのエンドポイントは `{"detail": "Invalid UUID format."}` を返します                                                                                   | リクエストを修正し、そのまま再試行しないでください                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `401`             | 認証情報がないか、無効です。[認証失敗時のレスポンス](#auth-errors)を参照してください                                                                                                                             | キーとヘッダー形式を確認し、そのまま再試行しないでください                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `402`             | プラン、Credits、または割当量が不足しています。[下記の説明](#payment-required)を参照してください                                                                                                                 | 組織管理者に通知してください                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `403`             | ロールの権限不足、組織での機能未開通、組織の無効化、または文字数課金プランの利用上限到達です                                                                                                                                 | ロール権限を調整するか、担当窓口にお問い合わせください                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `404`             | リソースが存在しない、キーの所属組織に属していない、または URL が間違っています                                                                                                                                     | ID、キーの所属組織、パスを確認してください                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `409`             | リソースの現在の状態と競合しています。同じジョブが実行中、削除対象のリソースが参照中などの場合です                                                                                                                              | 最新の状態を取得してから判断し、同じリクエストをそのまま再送しないでください                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `429`             | レート制限を超えています                                                                                                                                                                   | `Retry-After` に従って待機してください                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `5xx`             | プラットフォームまたは上流サービスのエラーです                                                                                                                                                        | 指数バックオフで再試行してください                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

`409` のレスポンスは `detail` オブジェクトです。一部のエンドポイントでは対処に必要なフィールドも含まれます。例えば、ナレッジベースで FAQ インポートがすでに実行中の場合は次のようになります。

```json
{"detail": "An FAQ import is already running for this knowledge base.", "jobId": "…"}
```

### 402：プラン、Credits、割当量の不足 <a href="#payment-required" id="payment-required"></a>

| 状況                                              | レスポンスの内容                                                                               | `code` の有無               |
| ----------------------------------------------- | -------------------------------------------------------------------------------------- | ------------------------ |
| 組織に有効な有料プランがありません                               | `{"detail": "Your organization has no active paid plan. …", "code": "no_active_plan"}` | あります。`no_active_plan` です |
| 組織の Credits が不足しています                            | `{"detail": "Insufficient credits …"}`。文言はエンドポイントによって異なります                             | ありません                    |
| メンバーの個人割当量が未割り当てまたは使い切られているか、所属ロールの割当量を使い切っています | `{"detail": "Personal credit quota exhausted. …"}`。文言は状況によって異なります                      | ありません                    |

* `code` が含まれるのは「有効な有料プランがない」場合のみです。Credits 不足や割当量の枯渇では `detail` のみが返ります。現時点では、レスポンスの内容だけで組織の Credits 不足と個人またはロールの割当量枯渇を区別できません。組織管理者に管理画面で確認してもらってください。
* Credits と割当量は、メッセージ送信、ナレッジベースファイルのアップロードと検索、Web ページのクロールなど、使用量が発生する書き込みリクエストで確認されます。参照用の `GET` リクエストがこれらの理由で `402` を返すことはありません。
* AI Gateway の OpenAI 互換エンドポイントは OpenAI 形式の `{"error": {"type": "billing_error", "code": "insufficient_credits", …}}` を返し、有効なプランがない場合も同じ `code` になります。
* プラットフォームで Credits 課金が有効になっていない場合（一部のオンプレミス環境など）、この種の `402` は発生しません。

## ページネーション <a href="#pagination" id="pagination"></a>

多くの一覧エンドポイントは、ページ番号によるページネーションを使用します。

| パラメーター                          | 説明                                                                       |
| ------------------------------- | ------------------------------------------------------------------------ |
| `page`                          | ページ番号は 1 から始まります。範囲外の場合は `404` と `{"detail": "Invalid page."}` が返ります     |
| `page_size`（`pageSize` も使用できます） | 1 ページあたりの件数です。デフォルトは 20、上限は 100 です。100 を超える値は自動的に 100 に切り詰められ、エラーにはなりません |

レスポンス形式は `{"count": …, "next": "…", "previous": "…", "results": [ … ]}` です。次のページを取得するには `next` の URL をそのまま使用します。次のページがない場合は `null` になります。

ほかに次の 2 つの形式があります。

* **カーソルページネーション**：会話一覧（`GET /api/v1/conversations/`）とメッセージ一覧（`GET /api/v1/messages/`）は `cursor` パラメーターを使用し、新しい順にページを取得します。`next` でさらに古いデータを取得できます。メッセージ一覧のレスポンスには `count` が含まれますが、会話一覧には含まれません。メッセージ一覧の各ページ内では、メッセージが古い順に並びます。
* **ページネーションなし**：一部の一覧は配列を直接返します。例えば `GET /api/v1/credit/items/` が該当します。

各エンドポイントがどの形式を使用するかは、そのエンドポイントのレスポンス例を確認してください。

## フィールド形式 <a href="#field-format" id="field-format"></a>

* **命名**：レスポンスのキーは常に camelCase です。リクエストの JSON とクエリパラメーターは camelCase と snake\_case の両方を受け付けます。JSON Schema、カスタム HTTP ヘッダー、metadata など、一部の自由形式フィールドの内容は大文字・小文字を変換せず、そのまま保持されます。
* **時刻**：多くの時刻フィールドは `"1759536000000"` のようなミリ秒の Unix タイムスタンプ文字列で出力されます。精度は秒単位です（末尾の 3 桁は常に `000` です）。一部のフィールドは ISO 8601 文字列を使用するため、各エンドポイントのページを確認してください。
* **小数**：金額や単価などの小数フィールドは `"316.8000000000"` のような文字列で出力されます。浮動小数点誤差を避けるため、十進数型で処理してください。
* **ID**：リソース ID の多くは UUID です。
* **言語**：エラーメッセージは `Accept-Language` ヘッダー（例：`ja`）に応じて翻訳されます。翻訳のないメッセージは英語のままです。メッセージの文字列に依存しないでください。

## アップロードサイズの上限 <a href="#upload-limits" id="upload-limits"></a>

アップロード上限はプラットフォームの設定によって決まり、変更される場合やオンプレミス環境で異なる場合があります。`GET /api/v1/allowed-file-specs/` のレスポンスを基準にしてください。このエンドポイントは認証不要で、用途ごとに許可される拡張子と `maxSize`（バイト単位）を返します。2026 年 10 月時点の本番環境の値は次のとおりです。

| 用途                                     | 上限     |
| -------------------------------------- | ------ |
| ナレッジベースファイル                            | 100 MB |
| 会話の添付ファイル：文書、スプレッドシート、プレゼンテーション、音声ファイル | 10 MB  |
| 会話の添付ファイル：画像                           | 5 MB   |
| 議事録用の音声ファイル                            | 100 MB |

* Presigned 方式でアップロードする場合、アップロード URL を取得する `POST /api/v1/upload-presigned-url/` の時点で `fileSize` と拡張子が確認されます。上限超過や許可されていない種類の場合は `400` が返ります。手順は技術者向けマニュアルの [Presigned ファイルアップロード方式](https://docs.maiagent.ai/tech/api-integration/api_knowledge)を参照してください。
* ナレッジベースのメタデータ、タグ、FAQ の Excel インポートにも、ナレッジベースファイルと同じ上限が適用されます。

## よくある質問 <a href="#faq" id="faq"></a>

<details>

<summary>キーは正しいのに、401 が返り続けるのはなぜですか？</summary>

`401` では理由は示されません。<mark style="color:blue;">API Key 管理</mark>で、キーが無効化、有効期限切れ、取り消しの状態でないことと、紐づくメンバーが引き続き有効であることを確認してください。ヘッダー形式は `Api-Key <キー>` である必要があります。`Bearer` を使用すると `token_not_valid` が返ります。[認証失敗時のレスポンス](#auth-errors)を参照してください。

</details>

<details>

<summary>特定の API だけを呼び出せるようにキーを制限できますか？</summary>

できません。キーの権限は紐づくメンバーのロール権限と同じです。必要なロールだけを持つ連携用メンバーでキーを発行してください。AI Gateway では、キーで呼び出せるモデルを別途制限できます。[AI Gateway：OpenAI 互換 API 連携](https://docs.maiagent.ai/tech/ai-gateway/ai-gateway-openai-compatible)を参照してください。

</details>

<details>

<summary>`/api/` で始まる例と `/api/v1/` の両方が使えるのはなぜですか？</summary>

どちらのプレフィックスも同じエンドポイント群を公開しています。AI Gateway と SCIM のみ `/api/v1/` が必須です。新しい連携では `/api/v1/` に統一してください。

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/api/ja/preparation/conventions.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
