> For the complete documentation index, see [llms.txt](https://docs.digitalhumans.jp/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalhumans.jp/itp-guide/api.md).

# API の概要

イマーシブトレーニングプラットフォームには、ユーザー・チーム・トレーニング・参照データをプログラムから操作できる REST API があります。ユーザーの一括登録、チームの管理、トレーニングの作成、受講データの出力などを自動化できます。

すべてのエンドポイントは、APIキーで認証された組織（お客様の組織）の範囲で動作します。

{% hint style="success" %}
**OpenAPI 仕様**\
API 全体の OpenAPI 3.0 仕様ファイルをダウンロードできます。Swagger UI や Postman、コード生成ツールで使えます。詳しくは「[OpenAPI 仕様](https://docs.digitalhumans.jp/itp-guide/api/openapi.md)」をご覧ください。
{% endhint %}

## ベースパス

```
https://training.uneeq.io/api/external/v1/organization/{organizationID}
```

`{organizationID}` には、お客様の組織 ID（`org_abc123` のような形式。UUID ではありません）を指定します。

## 認証

すべてのリクエストで、`Authorization` ヘッダーに APIキーを Bearer トークンとして付けます。

```
Authorization: Bearer your-api-key-here
```

APIキーの発行方法とコード例は「[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)」をご覧ください。

## エンドポイント一覧

### ユーザー

| メソッド   | エンドポイント                  | 内容                                  |
| ------ | ------------------------ | ----------------------------------- |
| `POST` | `/users/add`             | 組織にユーザーを追加する                        |
| `GET`  | `/users/page/{page}`     | 組織のユーザーを一覧する（クエリパラメーター `limit` が必須） |
| `POST` | `/users/roles/assign`    | ユーザーにロールを割り当てる                      |
| `PUT`  | `/users/{userID}/status` | ユーザーの状態を変更する                        |
| `PUT`  | `/users/{userID}`        | ユーザー情報（名前・メールアドレス・ロケール・テーマ）を変更する    |

詳しくは「[ユーザー](https://docs.digitalhumans.jp/itp-guide/api/users.md)」をご覧ください。

### チーム

| メソッド     | エンドポイント                            | 内容                                               |
| -------- | ---------------------------------- | ------------------------------------------------ |
| `POST`   | `/teams/create`                    | チームを作成する                                         |
| `PUT`    | `/teams/{teamID}`                  | チームを編集する                                         |
| `DELETE` | `/teams/{teamID}`                  | チームを削除する                                         |
| `GET`    | `/teams/page/{page}/limit/{limit}` | チームを一覧する                                         |
| `GET`    | `/teams/{teamID}`                  | チームを1件取得する                                       |
| `GET`    | `/teams/{teamID}/scenarios`        | チームに割り当てたシナリオを一覧する                               |
| `PUT`    | `/teams/{teamID}/scenarios`        | チームに割り当てるシナリオを置き換える                              |
| `POST`   | `/teams/{teamID}/tags`             | **廃止予定**。`204` を返しますが何も保存しません。2027-03-01 に削除されます |
| `DELETE` | `/teams`                           | チームをまとめて削除する                                     |

詳しくは「[チーム](https://docs.digitalhumans.jp/itp-guide/api/teams.md)」をご覧ください。

### チームメンバー

| メソッド     | エンドポイント                                           | 内容            |
| -------- | ------------------------------------------------- | ------------- |
| `POST`   | `/teams/{teamID}/users`                           | チームにユーザーを追加する |
| `DELETE` | `/teams/{teamID}/users/{userID}`                  | チームからユーザーを外す  |
| `PUT`    | `/teams/{teamID}/users/{userID}/role`             | チーム内の役割を設定する  |
| `GET`    | `/teams/{teamID}/users/page/{page}/limit/{limit}` | チームメンバーを一覧する  |

詳しくは「[チームメンバー](https://docs.digitalhumans.jp/itp-guide/api/team-members.md)」をご覧ください。

### トレーニング

| メソッド     | エンドポイント                                               | 内容                                |
| -------- | ----------------------------------------------------- | --------------------------------- |
| `POST`   | `/immersive-training/generate`                        | 平易な文章の概要からトレーニングを生成する             |
| `POST`   | `/immersive-training/role-play`                       | 指定した項目からロールプレイ（または練習用）トレーニングを作成する |
| `PUT`    | `/immersive-training/role-play/{immersiveTrainingID}` | ロールプレイを更新する                       |
| `POST`   | `/immersive-training/qa`                              | 質問リストから Q\&Aシナリオを作成する             |
| `PUT`    | `/immersive-training/qa/{immersiveTrainingID}`        | Q\&Aシナリオを更新する                     |
| `GET`    | `/immersive-training/page/{page}/limit/{limit}`       | トレーニングを一覧する                       |
| `GET`    | `/immersive-training/{immersiveTrainingID}`           | トレーニングを1件取得する                     |
| `DELETE` | `/immersive-training/{immersiveTrainingID}`           | トレーニングを削除する                       |

詳しくは「[トレーニング](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md)」をご覧ください。

### 参照データ

| メソッド  | エンドポイント                | 内容                                                  |
| ----- | ---------------------- | --------------------------------------------------- |
| `GET` | `/learning-domains`    | 学習ドメインを一覧する                                         |
| `GET` | `/use-cases`           | **廃止予定**。`/learning-domains` への `301` を返し、データは返しません |
| `GET` | `/persona-config`      | デジタルヒューマンを一覧する                                      |
| `GET` | `/default-assessments` | デフォルトの評価を取得する                                       |
| `GET` | `/tags`                | 組織のタグを一覧する（外部 API では読み取り専用）                         |

詳しくは「[参照データ](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md)」をご覧ください。

### データのエクスポート

| メソッド  | エンドポイント                    | 内容                  |
| ----- | -------------------------- | ------------------- |
| `GET` | `/export/sessions/summary` | セッションの要約（主要項目）を出力する |
| `GET` | `/export/sessions/details` | セッションの詳細をすべて出力する    |

詳しくは「[データのエクスポート](https://docs.digitalhumans.jp/itp-guide/api/data-export.md)」をご覧ください。

{% hint style="warning" %}
**廃止予定の項目**\
・`POST /teams/{teamID}/tags`: 何も保存しません。2027-03-01 に削除されます。代わりに `PUT /teams/{teamID}/scenarios` を使ってください\
・チームの `tags` フィールドと、`GET /teams/page/{page}/limit/{limit}` のクエリパラメーター `tags`: 2027-03-01 に削除されます\
・`GET /use-cases`: データを返さず、`/learning-domains` への `301` を返します。代わりに `GET /learning-domains` を使ってください（削除日は公表されていません）\
・トレーニングの `allow_ai_coach` フィールド: 常に `false` です。2027-03-15 に削除されます
{% endhint %}

## 将来の変更への備え（前方互換性） <a href="#forward-compatibility" id="forward-compatibility"></a>

{% hint style="warning" %}
**レスポンスを厳格な JSON モードで解析しないでください。**\
機能の追加に合わせて、既存のレスポンスに新しいフィールドが追加されます。未知のプロパティを拒否する設定のパーサーは、以前は受け付けていたレスポンスでエラーになります。認識できないフィールドは無視するよう、クライアントを設定してください。
{% endhint %}

レスポンスは「項目が増えることがある」前提で読んでください。

* **未知のフィールドは無視する。** 厳格な（網羅的な）デコードを無効にします。具体的には、`Newtonsoft.Json` で `MissingMemberHandling.Error` を使わない、Go の `encoding/json` で `DisallowUnknownFields()` を使わない、Jackson で `FAIL_ON_UNKNOWN_PROPERTIES` を使わない、Pydantic で `extra="ignore"` にする、検証に使うスキーマに `additionalProperties: false` を入れない、といった設定です。
* **認識できない enum の値は「未対応」として扱い、「不正」として扱わない。** 既存の enum に値が追加されることがあります（`scenario_type` と `endorsement_level` はその旨を明記しています）。対応する値だけを分岐で処理し、それ以外はエラーにせず適切に読み飛ばしてください。
* **フィールドの順序や、省略可能なフィールドが省略されたままであることに依存しない。** 「空のときは省略される」と記載されたフィールドも、関連する機能が使われ始めると返されるようになることがあります。

**文書化されたフィールドは、廃止の手続きを経ずに削除・名称変更されることはありません。** 廃止するフィールドは、まずドキュメントと OpenAPI 仕様で廃止予定と示され、その後も返され続け、告知のうえで後のバージョンで削除されます。例は次のとおりです。

* `GET /use-cases` は `GET /learning-domains` に置き換えられましたが、消えずに応答を返し続けています。
* `POST /teams/{teamID}/tags` は、2027-03-01 に削除されるまで、`204` と `Deprecation`・`Sunset`・`Link` ヘッダーを返します。
* 廃止予定の「フィールド」も同様です。トレーニングの `allow_ai_coach` は、AI コーチの提供終了により常に `false` になりましたが、2027-03-15 に削除されるまで返されます。

{% hint style="success" %}
**この約束の範囲**\
対象は、このドキュメントに記載したフィールドです。レスポンスには、ここに記載していないフィールドが含まれることがあります。それらは内部用で契約の対象外のため、予告なく変更・削除されることがあります。記載したフィールドだけを読み、それ以外は無視してください。
{% endhint %}

リクエストは逆の考え方でチェックされます。リクエストボディの未知のプロパティは拒否されず、無視されます。そのため、このバージョンで使われないフィールドを送っても問題ありません。

例外は、シナリオ作成系のエンドポイント（[`POST /immersive-training/generate`](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md)、`role-play` の2つ、`qa` の2つ）です。これらは認識できないフィールドに `400` を返します。フィールド名の綴りを間違えると、作成される内容が変わったり、更新時に「変更しない」と解釈されたりするのを防ぐためです。

## 共通の仕組み

### ページング

ページングには2つの方式があります。

**ページ番号方式**: 一覧系のエンドポイントで使います。ページ番号とページサイズを指定します。`page` は `1` から始まり、`limit` は `1`〜`100` です。

多くのエンドポイントでは、両方の値をパスで指定します。

```
GET /teams/page/1/limit/25
GET /teams/{teamID}/users/page/1/limit/25
GET /immersive-training/page/1/limit/25
```

`GET /users/page/{page}` だけは、`limit` をクエリパラメーターで指定します。`limit` は必須で、既定のページサイズはありません。

```
GET /users/page/1?limit=25
```

**オフセット方式**: 2つのエクスポート用エンドポイントで使います。`limit` と `offset` はどちらも省略可能なクエリパラメーターです（`limit` の既定値は `1000`、最大 `10000`）。これらはファイルとしてボディを返すため、総件数は `records` フィールドではなく、レスポンスヘッダー `X-Total-Count` で返されます。

```
GET /export/sessions/summary?limit=1000&offset=0
```

ページ番号方式のレスポンスには、結果とあわせて、条件に一致した総件数が含まれます。

```json
{
  "records": 42,
  "teams": [...]
}
```

### エラーレスポンス

エラーレスポンスの形は3種類あります。

**1. `message` のみ**: ハンドラーやサービスのエラー（`400`、`403`、`404`、`405`、`409`、`500`）で一般的な形です。

```json
{ "message": "A team with this name already exists for your organization" }
```

**2. `error_code` と `message`**: `POST /users/add` と、シナリオ作成系のエンドポイントが返します。分岐には、文言が変わる可能性のある `message` ではなく、変わらない `error_code` を使ってください。コードの一覧は「[ユーザー](https://docs.digitalhumans.jp/itp-guide/api/users.md)」と「[トレーニング](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md)」をご覧ください。

```json
{
  "error_code": "emails_required",
  "message": "emails: at least one email is required"
}
```

**3. `error` のみ**: 認証とレート制限のレスポンス（`401` と `429`）が返します。

```json
{ "error": "Invalid API key for this organization" }
```

{% hint style="success" %}
**エラーの扱い方**\
まず HTTP ステータスコードで判定してください。理由をユーザーやログに出すときは、両方のキーを読みます。認証とレート制限のレスポンスは `error`、それ以外は `message` に理由が入ります。
{% endhint %}

部分的に成功したレスポンス（`POST /users/add` が返す `207`）はエラーではありません。通常のレスポンスボディが返り、失敗した項目ごとに `results[]` の中に `error_code` が入ります。

{% hint style="success" %}
**安全な再試行**\
リクエストボディが正しい JSON でない場合、多くのエンドポイントは `500` と `{"message": "unable to decode request body"}` を返します。次の2つだけは `400` を返します。\
・`POST /users/add`: `error_code: invalid_request_body`\
・`PUT /teams/{teamID}/users/{userID}/role`: `{"message": "invalid request body"}`\
いずれの場合も原因はリクエストボディそのものなので、同じ内容で再送しても同じ結果になります。`5xx` だからと再試行せず、JSON を検証してください。
{% endhint %}

### HTTP ステータスコード

| コード   | 意味                                                                                                    |
| ----- | ----------------------------------------------------------------------------------------------------- |
| `200` | 成功                                                                                                    |
| `201` | 作成に成功（`POST /immersive-training/role-play` など）                                                        |
| `204` | 成功（ボディなし）                                                                                             |
| `207` | マルチステータス（部分的に成功）                                                                                      |
| `301` | 恒久的に移動。`GET /use-cases` だけが返し、`/learning-domains` へリダイレクトします                                          |
| `400` | 不正なリクエスト（検証エラー、または必須パラメーターの不足）                                                                        |
| `401` | 認証エラー（APIキーが無効、または未指定）。ボディは `error` キー                                                                |
| `403` | 禁止（例: 参照したタグが別の組織のもの）                                                                                 |
| `404` | リソースが見つからない                                                                                           |
| `405` | 許可されていない操作                                                                                            |
| `409` | 競合（チーム名の重複、メールアドレスが使用中）                                                                               |
| `413` | ペイロードが大きすぎる。シナリオ作成系のエンドポイント（`/immersive-training/generate`、`role-play`、`qa`）だけが返します。ボディの上限は 512 KB です |
| `429` | リクエストが多すぎる。ボディは `error` キー。「[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)」を参照   |
| `500` | サーバー内部エラー。リクエストボディが正しい JSON でない場合も返ります                                                                |

## 各ページへのリンク

| ページ                                                                         | 内容                               |
| --------------------------------------------------------------------------- | -------------------------------- |
| [認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)         | APIキーの発行と使い方、コード例                |
| [レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)         | APIキーごとのリクエスト上限と `429` の扱い       |
| [ユーザー](https://docs.digitalhumans.jp/itp-guide/api/users.md)                | ユーザーの追加、ロールの割り当て、状態の変更           |
| [チーム](https://docs.digitalhumans.jp/itp-guide/api/teams.md)                 | チームの作成・変更・削除、シナリオの割り当て           |
| [チームメンバー](https://docs.digitalhumans.jp/itp-guide/api/team-members.md)      | チームへの追加・削除、チーム内の役割               |
| [トレーニング](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md) | トレーニングの生成・作成・取得・削除               |
| [参照データ](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md)      | 学習ドメイン、デジタルヒューマン、評価、タグ           |
| [データのエクスポート](https://docs.digitalhumans.jp/itp-guide/api/data-export.md)    | 受講セッションのデータを JSON または xAPI 形式で出力 |
| [OpenAPI 仕様](https://docs.digitalhumans.jp/itp-guide/api/openapi.md)        | 仕様ファイルのダウンロードと使い方                |
