> 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/quickstart.md).

# クイックスタート

MaiAgent プラットフォーム API の呼び出しを始めるために、ベース URL、API キーの取得方法（メンバー自身による作成と管理者による発行）、キーの権限範囲、および最初のリクエスト例を説明します。

このページでは、プラットフォーム API を呼び出すための準備として、URL の確認、API キーの取得、最初のリクエストの送信までをご案内します。各エンドポイントのフィールドと完全な例は [API ドキュメント](https://docs.maiagent.ai/api) を参照してください。認証、レート制限、エラー形式など、エンドポイント共通のルールについては [API 共通規約](https://docs.maiagent.ai/api/preparation/conventions) を参照してください。

## API 連携ドキュメントとサンプルコード <a href="#examples" id="examples"></a>

{% embed url="<https://github.com/Playma-Co-Ltd/maiagent-api-examples/>" %}

## API のベース URL <a href="#base-url" id="base-url"></a>

```
https://api.maiagent.ai/api/v1/
```

オンプレミスおよびプライベートクラウド環境では、貴社のプラットフォームのドメインに置き換えてください。新しい連携では必ず `/api/v1/` プレフィックスを使用してください。詳細は [URL とバージョンプレフィックス](https://docs.maiagent.ai/api/preparation/conventions#base-url) を参照してください。

## API キーの取得 <a href="#get-api-key" id="get-api-key"></a>

API キーの取得方法は 2 種類あり、どちらのキーも呼び出し方法は同じです。

### メンバー自身による作成 <a href="#self-issued-key" id="self-issued-key"></a>

組織内の有効なメンバーは、追加の権限なしで、管理画面の右上のアバター → <mark style="color:blue;">アカウント</mark> → <mark style="color:blue;">API キー</mark> から自分用のキーを作成できます。キーは**現在切り替えている組織**に作成され、キー全体が表示されるのは作成時の一度だけです。操作手順は、ユーザーマニュアルの [メンバー自身によるキーの作成](https://docs.maiagent.ai/org/developer/api-keys#self-issued-keys) を参照してください。

### 管理者による発行 <a href="#admin-issued-key" id="admin-issued-key"></a>

「API Key 管理権限」を持つ管理者は、<mark style="color:blue;">組織設定</mark> → <mark style="color:blue;">API Key 管理</mark> から、指定したメンバー用のキーを発行できます。有効期限や 1 分あたりのリクエスト数（RPM）の設定、キーの無効化や取り消しもできます。操作手順は、ユーザーマニュアルの [API Key の作成](https://docs.maiagent.ai/org/developer/api-keys#create-api-key) を参照してください。

## キーの権限範囲 <a href="#key-scope" id="key-scope"></a>

キーは 1 人のメンバーに紐付きます。呼び出し時の組織と権限は、そのメンバーの組織内での身分とロール権限に基づきます。リクエストに組織 ID を別途含める必要はなく、エンドポイント別の権限スコープもありません。メンバーが無効化されるか組織から削除されると、キーは直ちに無効になります。詳細なルールと連携用キーの推奨事項は [API 共通規約：認証](https://docs.maiagent.ai/api/preparation/conventions#authentication) を参照してください。

## 最初のリクエストの送信 <a href="#first-request" id="first-request"></a>

`Authorization` ヘッダーに `Api-Key <キー>` の形式でキーを指定してください（`Bearer` ではありません）。

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

Agent の一覧を取得する例です。

```bash
curl https://api.maiagent.ai/api/v1/chatbots/ \
  -H "Authorization: Api-Key YOUR_API_KEY"
```

レスポンスはページネーション形式（`count`、`next`、`previous`、`results`）で、すべてのフィールド名は camelCase です。詳細は [ページネーション](https://docs.maiagent.ai/api/preparation/conventions#pagination) と [フィールド形式](https://docs.maiagent.ai/api/preparation/conventions#field-format) を参照してください。`401` が返された場合は、キーの状態とヘッダーの形式を確認してください。[エラーレスポンス](https://docs.maiagent.ai/api/preparation/conventions#errors) を参照してください。

## 次のステップ <a href="#next-steps" id="next-steps"></a>

* エンドポイントと認証の詳細：[API ドキュメント：API 認証方式](https://docs.maiagent.ai/api/preparation/authentication)
* エンドポイント共通のルール：[API 共通規約](https://docs.maiagent.ai/api/preparation/conventions)
* 会話の作成とメッセージ・添付ファイルの送信：[会話とメッセージの作成](/tech/ja/api-integration/conversations-and-messages.md)
* Agent の応答の取得（ストリーミングまたは同期）：[会話とメッセージの応答（ストリーミング／同期）](/tech/ja/api-integration/dui-hua-yu-xun-xi-hui-fu-chuan-liu-tong-bu.md)
* ナレッジベースのファイルと検索の管理：[ナレッジベースの利用—アップロード、検索、管理](/tech/ja/api-integration/knowledge-base-api.md)
* 会話イベントを自社システムに送信：[Webhook](/tech/ja/serve/webhook.md)


---

# 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/quickstart.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.