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

# OpenAPI 仕様

イマーシブトレーニングプラットフォームの外部 API 全体を、OpenAPI 3.0.3 形式の仕様ファイルで提供しています。Swagger UI や Postman に読み込んだり、コード生成ツールでクライアントを作ったりできます。

仕様ファイル（itp-openapi.yaml）は、次からダウンロードできます。

{% file src="/files/fT4TmW1SaEyhkIzKsuY4" %}
OpenAPI 3.0.3 形式の仕様ファイル
{% endfile %}

## Swagger UI で見る

1. [Swagger Editor](https://editor.swagger.io/) を開きます。
2. 「File」>「Import file」で、ダウンロードした `itp-openapi.yaml` を読み込みます。
3. 右側にエンドポイントの一覧が表示されます。各エンドポイントを開くと、パラメーターやレスポンスの形を確認できます。

実際にリクエストを送るには、「Authorize」をクリックして APIキーを入力し、「Servers」の `organizationID` をお客様の組織 ID（`org_abc123` のような形式）に変更します。

## Postman で使う

1. Postman で「Import」をクリックし、`itp-openapi.yaml` を選択します。
2. 仕様から作るコレクションとして読み込みます。エンドポイントがフォルダーごとに作成されます。
3. コレクションの「Authorization」で種類を「Bearer Token」にし、APIキーを入力します。
4. コレクションのベース URL に含まれる `{organizationID}` を、お客様の組織 ID（`org_abc123` のような形式）に置き換えます。

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

## 使うときの注意

* **厳格な検証に使わないでください。** この仕様から `additionalProperties: false` の検証を生成すると、項目が追加されたときにエラーになります。詳しくは「[API の概要](https://docs.digitalhumans.jp/itp-guide/api.md#forward-compatibility)」の「将来の変更への備え」をご覧ください。
* **廃止予定の項目も含まれます。** `deprecated: true` が付いた項目（`GET /use-cases`、`POST /teams/{teamID}/tags`、チームの `tags`、トレーニングの `allow_ai_coach` など）は、新しく使わないでください。
* Swagger UI や Postman から送ったリクエストは、お客様の組織のデータに実際に反映されます。試すときは、テスト用のユーザーやチームで行ってください。
