> 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/endpoint-behaviors/inbox-credit-quota-api.md).

# 会話プラットフォームの Credits 上限 API

API で対話プラットフォームの Credits 上限額を割り当て、予算を調整し、上限額の必須設定を切り替えます。対話プラットフォーム ID と上限額 ID の違い、および上限額の無効化による影響を説明します。

連携システムでは、Web Chat や LINE などの対話プラットフォームに Credits の利用上限を割り当て、AI の利用に上限額の設定を必須とするかどうかを切り替えられます。これは対話プラットフォーム単位の予算管理です。管理画面での操作や上限額を使い切ったときの動作については、ユーザーマニュアルの[対話プラットフォームの Credits 上限額管理](https://docs.maiagent.ai/others/credits/inbox-credit-quota)をご覧ください。

例えば、Web サイトのサービス事業者がキャンペーンごとに Web Chat を作成し、自社の管理システムから各キャンペーンの予算を割り当てたい場合を考えます。まずシステムでキャンペーンの対話プラットフォーム ID を取得し、上限額を作成してから再取得して確認します。キャンペーンを中止する場合、管理者は上限額を無効化するか、上限額の必須設定を解除できます。この 2 つの操作では効果が異なります。

## 呼び出し前の確認事項 <a href="#prerequisites" id="prerequisites"></a>

* この API は Credits 課金の組織に適用されます。呼び出し元には組織の **Credit 管理権限**が必要です。読み取りにもこの権限が必要です。
* [API 共通仕様](https://docs.maiagent.ai/tech/ja/api-integration/api-conventions.md#authentication)の API Key 認証を使用します。キーを所有するメンバーには、上記の権限が必要です。
* `inboxId` は**対話プラットフォーム ID**であり、Agent ID ではありません。同じ Agent でも、入口によって対話プラットフォームが異なる場合があります。MaiGPT の対話プラットフォームには、このページの上限額管理は適用されません。
* `quotaId` は上限額の作成時に返される `id` であり、対話プラットフォーム ID ではありません。

## エンドポイントの選択 <a href="#endpoints" id="endpoints"></a>

以下のパスはすべて、プラットフォームの URL の後に付加します。SaaS の例は `https://api.maiagent.ai` です。

| 目的                            | メソッドとパス                                                                                              |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| 組織の対話プラットフォームと上限額の概要を取得します    | `GET /api/v1/organizations/{organizationId}/credit-quota-inboxes/`                                   |
| 特定の対話プラットフォームの上限額レコードを一覧取得します | `GET /api/v1/inboxes/{inboxId}/credit-quotas/`                                                       |
| 上限額を割り当てます                    | `POST /api/v1/inboxes/{inboxId}/credit-quotas/`                                                      |
| 1 件の上限額を取得します                 | `GET /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/`                                             |
| 有効な上限額を変更します                  | `PATCH /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/`                                           |
| 上限額を無効化します                    | `DELETE /api/v1/inboxes/{inboxId}/credit-quotas/{quotaId}/`                                          |
| 上限額の必須設定を切り替えます               | `PATCH /api/v1/organizations/{organizationId}/credit-quota-inboxes/{inboxId}/credit-quota-required/` |

組織の対話プラットフォーム一覧には MaiGPT は含まれません。`search` で対話プラットフォーム名、Agent 名、対話プラットフォーム ID を検索できます。レスポンスのページネーション情報に従って、必要なデータをすべて取得してください。

{% hint style="info" %}
JSON フィールドには camelCase を使用します。上限額の一覧と詳細では、`quotaLimit`、`consumedAmount`、`remaining`、`isActive` などのフィールドが返されます。消費済みの上限額と組織ウォレットの残高を混同しないでください。
{% endhint %}

## 上限額の割り当て <a href="#allocate-quota" id="allocate-quota"></a>

対話プラットフォームの `credit-quotas/` パスに `POST` を送信します。以下はリクエストボディの例です。開始日時を実際のキャンペーンの日時に置き換えてください。

```json
{
  "quotaLimit": "500.000000",
  "validFrom": "2026-11-01T00:00:00+08:00",
  "validUntil": null,
  "resetPeriod": "none",
  "note": "キャンペーンのカスタマーサポート予算"
}
```

| フィールド         | 作成時の要件                                                                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `quotaLimit`  | 必須です。利用上限額は 0 以上である必要があります。最大 18 桁で、そのうち小数部は最大 6 桁です                                                                                                                      |
| `validFrom`   | 必須です。有効期間の開始日時です。例ではタイムゾーン付きの ISO 8601 形式を使用しています                                                                                                                         |
| `validUntil`  | 任意です。有効期限です。省略または `null` を指定すると、有効期限を設定しません。指定する場合は開始日時より後である必要があります。組織に有効な入金済み Credits がある場合は、その中で最も遅い有効期限を超えることもできません                                                   |
| `resetPeriod` | 任意です。`none`、`daily`、`weekly`、`monthly` のいずれかで、デフォルトは `none` です。周期ごとの動作は[リセット周期の設定](https://docs.maiagent.ai/others/credits/member-credit-quota#quota-reset-period)をご覧ください |
| `note`        | 任意です。備考です。デフォルトは空文字列です                                                                                                                                                    |

作成に成功すると、`201` と上限額データが返されます。返された上限額の `id` を保存し、1 件取得用の `GET` で再取得して確認してください。上限額を作成すると、その対話プラットフォームの上限額の必須設定も自動的に有効になります。

同じ対話プラットフォームで、2 件の上限額を同時に有効にすることはできません。有効な上限額がある場合は `PATCH` で変更するか、既存の上限額を無効化してから新しい上限額を割り当ててください。作成リクエストを繰り返し再送しないでください。

## 既存の上限額の調整 <a href="#update-quota" id="update-quota"></a>

1 件の上限額のパスに `PATCH` を送信し、変更するフィールドだけを含めます。例えば、次のように指定します。

```json
{
  "quotaLimit": "800.000000",
  "note": "キャンペーン延長に伴い予算を増額"
}
```

`quotaLimit`、`validUntil`、`note`、`resetPeriod` を調整できます。このエンドポイントでは開始日時を変更できません。また、無効化した上限額は変更できません。上限額を引き下げる場合、すでに消費した額を下回る値には設定できません。

## 上限額の無効化と必須設定の解除の違い <a href="#deactivate-vs-remove-requirement" id="deactivate-vs-remove-requirement"></a>

1 件の上限額に対する `DELETE` が成功すると `204` が返され、**上限額が無効化されます**。上限額レコードは削除されず、上限額の必須設定も解除されません。対話プラットフォームで引き続き上限額が必須の場合、無効化後は利用できる有効な上限額がなくなるため、AI の返信が制限されます。

**対話プラットフォームの上限額による制限を解除**するには、上記の `credit-quota-required/` パスに次の内容を送信します。

```json
{
  "creditQuotaRequired": false
}
```

これにより上限額の必須設定が解除され、既存の有効な上限額も無効化されます。逆に `true` を送信すると、上限額の必須設定だけが有効になり、新しい上限額は自動で割り当てられません。切り替えに成功すると、`200` と更新後の対話プラットフォームの上限額概要が返されます。`creditQuotaRequired` を確認してから、1 件の上限額を取得して状態を確認してください。

{% hint style="warning" %}
対話プラットフォームの上限額による制限を解除しても、組織ウォレットへの補充は行われず、ほかの適用対象の上限額制限も解除されません。管理階層の全体像については、ユーザーマニュアルの[3 層の上限額の組み合わせ](https://docs.maiagent.ai/others/credits/inbox-credit-quota#quota-layers)をご覧ください。
{% endhint %}


---

# 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/endpoint-behaviors/inbox-credit-quota-api.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.
