> 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/tech/ja/api-integration/api-conventions.md).
# API 共通仕様
MaiAgent プラットフォーム API を呼び出す際の共通ルールの概要です。URL とバージョンプレフィックス、API Key 認証、レート制限、エラーレスポンス、ページネーション、フィールド形式、アップロードサイズの上限をまとめています。正式な仕様は API ドキュメントを参照してください。
API エンドポイント間の共通ルールは、API ドキュメントの [API 共通仕様](https://docs.maiagent.ai/api/preparation/conventions) を正式な仕様としています。連携を開発する際は、そのページを基準にしてください。このページでは各節の概要を 1〜2 文でまとめ、API ドキュメントの同名の節にリンクしています。
{% hint style="info" %}
各エンドポイントのフィールドと例は [API ドキュメントサイト](https://docs.maiagent.ai/api) を参照してください。API Key の作成・管理に関する画面操作は、ユーザーマニュアルの [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys) を参照してください。
{% endhint %}
## URL とバージョンプレフィックス
SaaS の API URL は `https://api.maiagent.ai/api/v1/` です。オンプレミスとプライベートクラウドでは、ドメインを貴社のプラットフォームドメインに置き換えてください。新しい連携では必ず `/api/v1/` を使用してください。詳細は [API 共通仕様：URL とバージョンプレフィックス](https://docs.maiagent.ai/api/preparation/conventions#base-url) を参照してください。
## 認証
サーバー間の呼び出しでは、`Authorization` ヘッダーに `Api-Key <キー>` を指定します。キーは 1 人のメンバーに紐づき、そのメンバーのロールと同じ権限を持ちます。キーが無効になる条件、認証失敗時のレスポンス、連携用キーの推奨事項は [API 共通仕様：認証](https://docs.maiagent.ai/api/preparation/conventions#authentication) を参照してください。
各メンバーは複数の有効なキーを同時に保有でき、数に上限はありません（ユーザーマニュアルの [API Key 管理](https://docs.maiagent.ai/org/developer/api-keys#key-concepts) を参照してください）。キーは API でも発行できます。管理者がメンバーに代わって発行する場合は `POST /api/v1/organizations/{organizationPk}/api-keys/` を使用します（「API Key 管理権限」が必要で、名前、有効期限、RPM を設定できます）。メンバーが自身で作成する場合は `POST /api/v1/organizations/{organizationPk}/my-api-keys/` を使用し、取り消す場合は対応する `DELETE` を使用します。完全なキーは作成時のレスポンスに一度だけ表示されます。フィールドは API ドキュメントの [組織とメンバー](https://docs.maiagent.ai/api/api-reference/zu-zhi-he-cheng-yuan) を参照してください。
## レート制限
プラットフォーム API には、デフォルトのグローバル上限はありません。主な制限は API Key ごとの RPM と AI Gateway の TPM です。上限を超えると、`Retry-After` を含む `429` が返されます。レート制限の対象範囲の詳細は [API 共通仕様：レート制限](https://docs.maiagent.ai/api/preparation/conventions#rate-limits) を参照してください。
## エラーレスポンス
エラーは HTTP ステータスコードと `code` で判断し、`detail` の文字列との照合は避けてください。エラーレスポンスの構造、各ステータスコードへの推奨対応、`402` が返されるケースは [API 共通仕様：エラーレスポンス](https://docs.maiagent.ai/api/preparation/conventions#errors) を参照してください。
## ページネーション
多くのリストは `page` と `page_size` によるページ番号方式のページネーションを使用します（デフォルトは 20、上限は 100 です）。`next` で次のページを取得します。会話とメッセージのリストはカーソル方式のページネーションを使用します。詳細は [API 共通仕様：ページネーション](https://docs.maiagent.ai/api/preparation/conventions#pagination) を参照してください。
## フィールド形式
レスポンスのキーはすべて camelCase です。日時フィールドは主にミリ秒単位のタイムスタンプ文字列です。詳細は [API 共通仕様：フィールド形式](https://docs.maiagent.ai/api/preparation/conventions#field-format) を参照してください。
## アップロードサイズの上限
アップロードの上限は `GET /api/v1/allowed-file-specs/` のレスポンスを基準にしてください。用途別の現在の値は [API 共通仕様：アップロードサイズの上限](https://docs.maiagent.ai/api/preparation/conventions#upload-limits) を参照してください。Presigned アップロードの流れは [Presigned ファイルアップロード方式](/tech/ja/api-integration/api_knowledge.md) を参照してください。
## リクエスト内容のエンコーディング
リクエストとレスポンスの JSON はすべて UTF-8 です。ロールの指示（`instructions`）やメッセージ内容などのフィールドには、中国語やその他の Unicode 文字を直接指定でき、ASCII への変換やエスケープは不要です。リクエストに `Content-Type: application/json` を指定し、HTTP クライアントが UTF-8 で送信することを確認してください。レスポンスの JSON も UTF-8 の文字をそのまま返し、`\uXXXX` には変換しません。更新後、対応する `GET` で読み戻すと、保存された内容を確認できます。管理画面にも同じデータが表示されます。
## リクエストサイズと 413
* プラットフォーム API 自体は `413` を返しません。JSON リクエストボディが Django のデフォルト上限（2.5 MB）を超えると `400` を返します。この上限は JSON とフォームフィールドのみを対象とし、multipart のファイル本体は含みません。
* ファイルサイズの上限は `GET /api/v1/allowed-file-specs/` で決まります。上限を超えると、アップロード URL の取得またはファイル登録の段階で `400` を返します。[アップロードサイズの上限](#upload-limits) を参照してください。
* `413` を受信した場合は、プラットフォームの手前にあるプロキシ層（CDN／ロードバランサー）がリクエスト全体をブロックしたことを示します。通常、ファイルを Base64 で JSON に埋め込むか、大きなファイルを multipart で直接送信した場合に発生します。[Presigned ファイルアップロード方式](/tech/ja/api-integration/api_knowledge.md) に切り替えてください。ファイルをストレージに直接アップロードし、API リクエストにはファイルのキーだけを指定します。
## よくある質問
キーで常に `401` が返される場合、キーの呼び出し範囲を制限できるかどうか、`/api/` と `/api/v1/` の違いについては [API 共通仕様：よくある質問](https://docs.maiagent.ai/api/preparation/conventions#faq) を参照してください。
---
# 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/tech/ja/api-integration/api-conventions.md?ask=&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.