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

# トレーニング

トレーニング（シナリオ）を API で生成・作成・更新・一覧取得・取得・削除できます。

{% hint style="info" %}
**トレーニングの作り方は2通りあります。**\
[AI で生成する](#generate)と、簡単な説明文（ブリーフ）から内容一式を自動で作成します。\
[ロールプレイシナリオを作成する](#create-role-play)・[Q\&Aシナリオを作成する](#create-qa)は、お客様が用意した完成済みの内容をそのまま登録します。どちらにも対応する更新用のエンドポイントがあります。
{% endhint %}

## エンドポイント一覧

| メソッド     | エンドポイント                                               | 内容                                   |
| -------- | ----------------------------------------------------- | ------------------------------------ |
| `POST`   | `/immersive-training/generate`                        | [AI でトレーニングを生成する](#generate)         |
| `GET`    | `/immersive-training/page/{page}/limit/{limit}`       | [トレーニングの一覧を取得する](#list)              |
| `GET`    | `/immersive-training/{immersiveTrainingID}`           | [トレーニングを取得する](#get)                  |
| `POST`   | `/immersive-training/role-play`                       | [ロールプレイシナリオを作成する](#create-role-play) |
| `PUT`    | `/immersive-training/role-play/{immersiveTrainingID}` | [ロールプレイシナリオを更新する](#update-role-play) |
| `POST`   | `/immersive-training/qa`                              | [Q\&Aシナリオを作成する](#create-qa)          |
| `PUT`    | `/immersive-training/qa/{immersiveTrainingID}`        | [Q\&Aシナリオを更新する](#update-qa)          |
| `DELETE` | `/immersive-training/{immersiveTrainingID}`           | [トレーニングを削除する](#delete)               |

すべてのパスは、ベースURL `https://training.uneeq.io/api/external/v1/organization/{orgID}` からの相対パスです。認証には APIキーを使います（[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)）。コード例の `BASE_URL`・`headers`・`API_KEY` の用意のしかたは [API の概要](https://docs.digitalhumans.jp/itp-guide/api.md) をご覧ください。

本ページでは、endorsement（所定の点数に達したことを認める仕組み）を、画面の表記に合わせて「合格認定」と書きます。

### トレーニングの種別（`scenario_type`） <a href="#scenario-types" id="scenario-types"></a>

`scenario_type` はすべてのトレーニングに含まれ、セッションの進め方を決めます。

| 値                  | 意味                             |
| ------------------ | ------------------------------ |
| `ROLE_PLAY`        | デジタルヒューマンと会話するロールプレイシナリオ       |
| `TECHNICAL_ACUMEN` | 会話ではなく、採点される質問に順に答えるQ\&Aシナリオ   |
| `PRACTICE`         | 作成したメンバー本人だけが使える、非公開の練習用ロールプレイ |

値は今後追加される可能性があります。知らない値が返ってきても、エラーとして扱わず「お客様のシステムでは扱わない種別」として処理してください。

### エラーレスポンスの形式

エラーの本文は、原則として `message` に内容が入ります。一部のエンドポイントは、機械的に判定できる `error_code` も返します。`message` の文言は変わることがあるため、分岐には `error_code` を使ってください。

```json
{ "message": "description of the error", "error_code": "validation_failed" }
```

認証エラー（`401`）とレート制限（`429`）だけは形式が異なり、内容は `message` ではなく `error` に入ります。`429` には、再試行までの待ち秒数を示す `Retry-After` ヘッダーが付きます。詳しくは [認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)・[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md) をご覧ください。

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

***

## AI でトレーニングを生成する <a href="#generate" id="generate"></a>

画面のシナリオ作成で「生成」を押したときと同じ作成の流れを、1回の呼び出しで実行します。練習したい場面を普通の文章で渡すと、デジタルヒューマンの人物設定、システムプロンプト、受講者への説明、評価基準が生成され、トレーニングが作成されます。レスポンスでは、そのトレーニングを開始するリンクが返ります。

```
POST /immersive-training/generate
```

{% hint style="warning" %}
**この呼び出しには30〜90秒かかります。**\
1回のリクエストの中で、AI による生成を何段階も続けて行うためです。クライアント側のタイムアウトは120秒以上に設定してください。多くの HTTP ライブラリの既定のタイムアウトでは足りません。
{% endhint %}

### 作成されるトレーニングの種類

作成されるトレーニングの種類は `user_email` だけで決まります。リクエストのほかの項目では変わりません。

| `user_email` | 作成されるもの                                             | 閲覧できる人       | 公開状態                            |
| ------------ | --------------------------------------------------- | ------------ | ------------------------------- |
| **指定しない**    | 組織全体向けのロールプレイシナリオ（`scenario_type: ROLE_PLAY`）       | 組織の全員        | `is_published` で指定（既定は `false`） |
| **指定する**     | そのメンバーが所有する非公開の練習用トレーニング（`scenario_type: PRACTICE`） | **そのメンバーだけ** | 常に公開済み                          |

Q\&Aシナリオ（`TECHNICAL_ACUMEN`）はこのエンドポイントでは生成できません。Q\&Aシナリオは画面で作成するか、[Q\&Aシナリオを作成する](#create-qa)を使ってください。

### 事前に用意するもの

* 学習ドメインの ID。[学習ドメインの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-learning-domains)で確認できます。
* **非公開の練習用トレーニングを作る場合のみ:** 組織で練習モード（practice mode）が有効になっていること、および組織の**有効なメンバー**のメールアドレス。必要に応じて、先に [`POST /users/add`](https://docs.digitalhumans.jp/itp-guide/api/users.md) でメンバーを追加してください。組織全体向けのロールプレイシナリオには、どちらも不要です。

組織で練習モードが有効になっているか分からない場合は、[弊社にお問い合わせください](https://www.digitalhumans.com/jp/contact)。なお、画面では、トレーニングの一覧の「練習シナリオを作成」から、自分だけが使える練習シナリオを作れます。API の練習モードと画面の練習シナリオの関係についても、上記の窓口にお問い合わせください。

### リクエストボディ

| フィールド                   | 型                      | 必須  | 説明                                                                                                                                                                                          |
| ----------------------- | ---------------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `learning_domain_id`    | string (UUID)          | はい  | トレーニングが属する学習ドメイン                                                                                                                                                                            |
| `scenario_context`      | string                 | はい  | 練習したい場面を普通の文章で説明したもの。最大50,000文字。説明に無いことは問い合わせではなく推測で補われるため、実際の情報をできるだけ詳しく書いてください                                                                                                            |
| `user_email`            | string（email）          | いいえ | 組織の有効なメンバー。指定すると、そのメンバー所有の非公開の練習用トレーニングを作成します。指定しないと、組織全体向けのロールプレイシナリオを作成します。最大254文字                                                                                                        |
| `documentation_text`    | string                 | いいえ | 生成するトレーニングに反映させる補足資料。最大50,000文字                                                                                                                                                             |
| `persona_config_id`     | string (UUID)          | いいえ | 使うデジタルヒューマンを固定します。標準で用意されたデジタルヒューマンか、お客様の組織のデジタルヒューマンを指定します（[デジタルヒューマンの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-digital-humans)）。指定しないと、場面に合うものが自動で選ばれます |
| `scenario_name`         | string                 | いいえ | 生成されるトレーニング名の代わりに使う名前。最大255文字                                                                                                                                                               |
| `locales`               | string                 | いいえ | トレーニングを提供する言語（ロケール）を**コロン**区切りで指定します。例: `en-US`、`en-US:fr-FR`、`ja-JP`、`ja-JP:en-US`。最大50文字。指定しないと英語で実施されます                                                                                  |
| `time_limit_minutes`    | integer                | いいえ | セッションの制限時間（分）。`1`〜`120`。指定しないと制限時間なし                                                                                                                                                        |
| `is_published`          | boolean                | いいえ | 組織全体向けの場合のみ。既定は `false` で、下書きとして作成されます                                                                                                                                                      |
| `tags`                  | array of string (UUID) | いいえ | 組織全体向けの場合のみ。最大50件。[タグの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-tags)で確認できます                                                                              |
| `endorsement_threshold` | integer                | いいえ | 組織全体向けの場合のみ。合格認定に必要な点数（%）。`1`〜`100`                                                                                                                                                         |

{% hint style="info" %}
**日本語のトレーニングを作る場合**\
`locales` には `ja-JP` のように地域まで含めた形で指定します。`ja` だけではエラーになります。\
`ja-JP` を指定しても、生成される内容（トレーニング名・人物設定・システムプロンプト・評価基準など）は、初回は英語で出力されることがあります。日本語に直す場合は、画面の「AIで調整」を使うか、[ロールプレイシナリオを更新する](#update-role-play)で内容を書き換えてください。
{% endhint %}

{% hint style="warning" %}
**このエンドポイントは、定義されていないフィールドを受け付けません。**\
ほかのエンドポイントと異なり、定義されていないフィールドが含まれていると、無視せずに `400` を返します。これは意図した仕様です。たとえば `user_email` のつづりを間違えると、非公開の練習用トレーニングのつもりが組織全体向けのトレーニングとして作成されてしまうためです。フィールド名は上の表と照らし合わせてください。
{% endhint %}

組織全体向けの3項目（`is_published: true`・`tags`・`endorsement_threshold`）は、`user_email` と同時に指定できません。練習用トレーニングはこれらを持たないため、同時に送ると `400` になります。なお、`user_email` と `is_published: false` の組み合わせは受け付けられ、通常どおり練習用トレーニングが作成されます。

ファイルのアップロードはこのエンドポイントではできません。補足資料は `documentation_text` に文章で渡してください。

```json
{
  "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "scenario_context": "A renewal negotiation with a procurement lead who has been happy with the service but is under orders to cut 20% from the contract. Other vendors have quoted lower.",
  "documentation_text": "Renewal playbook: lead with realised efficiency gains before discussing price.",
  "locales": "en-US",
  "is_published": true,
  "tags": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "endorsement_threshold": 70,
  "time_limit_minutes": 15
}
```

### レスポンス

**200 OK:**

```json
{
  "id": "7a906c1a-d885-4483-8947-85d88d39a41d",
  "role_play_url": "https://training.uneeq.io/immersive-training/conversation/7a906c1a-d885-4483-8947-85d88d39a41d"
}
```

| フィールド           | 型             | 説明                      |
| --------------- | ------------- | ----------------------- |
| `id`            | string (UUID) | 作成されたトレーニングの ID         |
| `role_play_url` | string        | トレーニングを開いてセッションを開始するリンク |

リンクは、お客様の環境に設定されたアドレスをもとに組み立てられます。そのため、ホスト名やパスの先頭部分は環境によって異なります。リンクを自分で組み立てず、返された値をそのまま受講者に渡してください。受講者に配る前に、リンクを開いて正しくトレーニング画面が表示されることをご確認ください。

レスポンスの本文はこれだけです。生成された内容（名前・人物設定・システムプロンプト・評価基準）を読み出すには、返された `id` で[トレーニングを取得する](#get)を呼び出してください。

{% hint style="warning" %}
**非公開の練習用トレーニングは、API で読み出せません。**\
[トレーニングを取得する](#get)は、所有者以外には `404` を返します。APIキーは所有者のメンバーとはみなされません。ID とリンクが返るのはこのレスポンスだけなので、後で必要な場合は保存しておいてください。\
また、そのリンクは所有者のメンバーしか使えません。ほかの人が開くと「見つかりません」のページが表示されます。\
組織全体向けのロールプレイシナリオには、どちらの制限もありません。
{% endhint %}

{% hint style="success" %}
**詳しく渡すほど、狙いどおりの内容になります。**\
画面での作成では、ロールプレイの成立に必要な情報が説明に足りないと、作成の途中で確認の質問が表示されます。このエンドポイントには質問に答える作成者がいないため、足りない情報は推測で補われます。学習ドメインに沿ったもっともらしい内容にはなりますが、お客様の実情とは異なります。\
`scenario_context` が1行だけでもトレーニングは一通り作成されますが、実際の状況や `documentation_text` はできるだけ多く渡してください。
{% endhint %}

生成された評価基準は、すべて新しいトレーニングに設定されます。同時に、組織で共有している評価基準のライブラリにも追加され、画面で作成した評価基準と並んで表示されます。重複はまとめられないため、大量に生成する連携では、ライブラリによく似た評価基準が少しずつ増えていきます。

{% hint style="success" %}
**冪等性キー（idempotency key）はありません。**\
クライアントが途中で待つのをやめても、サーバー側ではトレーニングが作成されていることがあります。そのまま再試行すると、2件目が作成されます。再試行するより、タイムアウトを長めに取ってください。\
練習用トレーニングの場合、このように取り残されたトレーニングは API で探すことも削除することもできません。
{% endhint %}

### エラー

| コード   | `error_code`           | 原因                                                                                                |
| ----- | ---------------------- | ------------------------------------------------------------------------------------------------- |
| `400` | `invalid_request_body` | JSON の形式が正しくない、またはこのエンドポイントで定義されていないフィールド名が含まれている                                                 |
| `400` | `validation_failed`    | いずれかのフィールドが検証に失敗した、または `locales` に対応していないロケールが含まれている。どのフィールドかはメッセージに示されます                         |
| `400` | —                      | 組織で練習モードが有効になっていない、または `tags`・`endorsement_threshold`・`is_published: true` を `user_email` と同時に送った |
| `401` | —                      | APIキーが無い、または無効                                                                                    |
| `404` | `user_not_in_org`      | `user_email` が組織の有効なメンバーではない                                                                      |
| `404` | `validation_failed`    | `tags` に組織のものではないタグが含まれている                                                                        |
| `404` | —                      | `learning_domain_id` が組織のものではない、`persona_config_id` が組織で使えない、または組織に割り当てられるデジタルヒューマンが無い            |
| `413` | `invalid_request_body` | リクエストボディが512KBを超えている                                                                              |
| `429` | —                      | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照                  |
| `500` | —                      | 生成に失敗した。`scenario_context` を詳しくして再試行するか、`scenario_name` を明示して再試行するかが、メッセージに示されます                  |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/generate" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  --max-time 180 \
  -d '{
    "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "scenario_context": "A renewal negotiation with a procurement lead under orders to cut 20% from the contract.",
    "is_published": true,
    "time_limit_minutes": 15
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    f"{BASE_URL}/immersive-training/generate",
    headers=headers,
    json={
        "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
        "scenario_context": (
            "A renewal negotiation with a procurement lead under orders "
            "to cut 20% from the contract."
        ),
        "is_published": True,
        "time_limit_minutes": 15,
    },
    timeout=180,
)
training = response.json()
print(training["id"], training["role_play_url"])
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/immersive-training/generate`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    learning_domain_id: 'b2c3d4e5-f6a7-8901-bcde-f23456789012',
    scenario_context:
      'A renewal negotiation with a procurement lead under orders to cut 20% from the contract.',
    is_published: true,
    time_limit_minutes: 15,
  }),
  signal: AbortSignal.timeout(180_000),
});
const { id, role_play_url } = await response.json();
```

{% endtab %}
{% endtabs %}

非公開の練習用トレーニングを作る場合は、`user_email` を加え、組織全体向けの項目を外します。

```json
{
  "user_email": "member@example.com",
  "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "scenario_context": "A renewal negotiation with a procurement lead under orders to cut 20% from the contract.",
  "time_limit_minutes": 15
}
```

***

## トレーニングの一覧を取得する <a href="#list" id="list"></a>

トレーニングの一覧をページ単位で取得します。

```
GET /immersive-training/page/{page}/limit/{limit}
```

### パスパラメーター

| パラメーター  | 型       | 説明                    |
| ------- | ------- | --------------------- |
| `page`  | integer | ページ番号（1から始まる）         |
| `limit` | integer | 1ページあたりの件数（`1`〜`100`） |

### クエリパラメーター

| パラメーター               | 型             | 説明                                                                                             |
| -------------------- | ------------- | ---------------------------------------------------------------------------------------------- |
| `search`             | string        | トレーニング名で検索します                                                                                  |
| `tags`               | string        | 絞り込みに使うタグ ID をカンマ区切りで指定します                                                                     |
| `is_published`       | string        | 小文字の `true` を送ると公開済みのトレーニングだけを、それ以外の値（`false` など）を送ると未公開のトレーニングだけを返します。省略すると両方を返します            |
| `learning_domain_id` | string (UUID) | 学習ドメインで絞り込みます                                                                                  |
| `sort_by`            | string        | 並び順。`name_asc`（既定）、`name_desc`、`updated_at_desc`、`updated_at_asc`。知らない値を指定すると `name_asc` になります |

### レスポンス

**200 OK:**

```json
{
  "records": 12,
  "immersive_trainings": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "status": "PUBLISHED",
      "name": "Discovery Call Practice",
      "persona_config": { "id": "config-uuid" },
      "personality_name": "Sarah Chen",
      "personality_role": "VP of Marketing",
      "version": 1,
      "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "is_published": true,
      "participant_instructions": "Open with a discovery question.",
      "locales": "en-US",
      "allow_ai_coach": false,
      "endorsement_level": "STANDARD",
      "endorsement_threshold": 80,
      "scenario_type": "ROLE_PLAY",
      "tags": [
        { "id": "tag-uuid", "name": "Sales", "color": "#3b82f6" }
      ],
      "assessments": [
        { "id": "assessment-uuid", "title": "Discovery Skills" }
      ],
      "updated_at": "2025-01-16T14:22:00Z",
      "created_at": "2025-01-15T10:30:00Z"
    }
  ]
}
```

| フィールド                      | 型                 | 説明                                                                                                                               |
| -------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `records`                  | integer           | 条件に合うトレーニングの総数（全ページ分）                                                                                                            |
| `immersive_trainings`      | array             | このページのトレーニング。該当が無いページでは `[]` ではなく `null`                                                                                         |
| `id`                       | string (UUID)     | トレーニング ID                                                                                                                        |
| `status`                   | string            | 作成上の状態。常に含まれ、状態が一度も変わっていないトレーニングでは空文字。公開中かどうかの判定には `is_published` を使ってください                                                       |
| `name`                     | string            | トレーニング名                                                                                                                          |
| `persona_config`           | object            | トレーニングに設定されたデジタルヒューマン（[デジタルヒューマンの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-digital-humans)を参照） |
| `personality_name`         | string            | デジタルヒューマンが演じる人物の名前                                                                                                               |
| `personality_role`         | string            | デジタルヒューマンが演じる人物の役職・役割                                                                                                            |
| `version`                  | integer           | トレーニングのバージョン番号                                                                                                                   |
| `learning_domain_id`       | string (UUID)     | トレーニングが属する学習ドメイン                                                                                                                 |
| `is_published`             | boolean           | 受講者が受講できる状態かどうか                                                                                                                  |
| `participant_instructions` | string            | 開始前に受講者に表示される説明                                                                                                                  |
| `training_scenario_id`     | string (UUID)     | 同じトレーニングのすべてのバージョンに共通の ID。バージョン管理の導入前に作成されたトレーニングには含まれません                                                                        |
| `locales`                  | string            | トレーニングを提供する言語                                                                                                                    |
| `allow_ai_coach`           | boolean           | **廃止予定**。下の注意を参照                                                                                                                 |
| `scenario_type`            | string            | `ROLE_PLAY`、`TECHNICAL_ACUMEN`、`PRACTICE` のいずれか（[トレーニングの種別](#scenario-types)を参照）                                                 |
| `endorsement_level`        | string            | 必要な合格認定のレベル。`NONE` または `STANDARD`。今後レベルが追加される可能性があるため、`NONE` 以外は「何らかのレベルの合格認定が必要」として扱ってください                                      |
| `endorsement_threshold`    | integer           | 合格認定に必要な点数（%）。合格認定を求めないトレーニングには含まれません                                                                                            |
| `question_ordering`        | string            | `SEQUENTIAL` または `RANDOM`。`TECHNICAL_ACUMEN` のみ。ほかの種別には含まれません                                                                    |
| `questions_per_session`    | integer           | 1回のセッションで出題する質問数。`TECHNICAL_ACUMEN` のみ。すべての質問を出題する場合は含まれません                                                                      |
| `tags`                     | array             | トレーニングのタグ（`id`・`name`・`color`）。タグが無い場合は `null`                                                                                   |
| `assessments`              | array             | トレーニングに設定された評価基準の `id` と `title`。無い場合は `null`                                                                                    |
| `updated_at`               | string (ISO 8601) | 最終更新日時。一度も編集されていない場合は含まれません                                                                                                      |
| `created_at`               | string (ISO 8601) | 作成日時                                                                                                                             |

{% hint style="warning" %}
**`allow_ai_coach` は廃止予定です（2027-03-15 に削除）。**\
セッション中に受講者の発話へリアルタイムで助言していた機能（AI コーチ）は提供を終了しました。そのため、この値は常に `false` です。互換性のために残されていますが、2027年3月15日に削除されます。この値による分岐はやめてください。
{% endhint %}

### エラー

| コード   | 原因                                                                               |
| ----- | -------------------------------------------------------------------------------- |
| `401` | APIキーが無い、または無効                                                                   |
| `429` | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X GET \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/page/1/limit/10?is_published=true" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(
    f"{BASE_URL}/immersive-training/page/1/limit/10",
    headers=headers,
    params={"is_published": "true"}
)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(
  `${BASE_URL}/immersive-training/page/1/limit/10?is_published=true`,
  { headers: { 'Authorization': `Bearer ${API_KEY}` } }
);
const data = await response.json();
```

{% endtab %}
{% endtabs %}

***

## トレーニングを取得する <a href="#get" id="get"></a>

ID を指定して、トレーニングを1件取得します。生成されたプロンプト全文や添付資料も含まれます。

```
GET /immersive-training/{immersiveTrainingID}
```

### パスパラメーター

| パラメーター                | 型             | 説明         |
| --------------------- | ------------- | ---------- |
| `immersiveTrainingID` | string (UUID) | トレーニングの ID |

### レスポンス

**200 OK** — トレーニングの全項目を返します。

```json
{
  "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
  "status": "PUBLISHED",
  "name": "Discovery Call Practice",
  "objective": "Identify three customer pain points",
  "context": "You are meeting a VP of Marketing...",
  "persona_config": { "id": "config-uuid" },
  "personality": "Skeptical but open to new ideas",
  "personality_name": "Sarah Chen",
  "personality_role": "VP of Marketing",
  "personality_location": "San Francisco",
  "personality_type": "prospect",
  "generated_prompt": "You are Sarah Chen, a VP of Marketing...",
  "prompt_summary": "Skeptical VP of Marketing evaluating a new vendor",
  "version": 1,
  "learning_domain_id": "learning_domain_uuid",
  "organization_id": "org_abc123",
  "is_published": false,
  "participant_instructions": "Open with a discovery question.",
  "locales": "en-US",
  "allow_ai_coach": false,
  "prompt_only_mode": false,
  "endorsement_level": "STANDARD",
  "endorsement_threshold": 80,
  "scenario_type": "ROLE_PLAY",
  "tags": null,
  "assessments": [
    { "id": "assessment-uuid", "title": "Discovery Skills", "description": "...", "weight": 10 }
  ],
  "documents": [
    { "id": "doc-uuid", "file_name": "product-overview.pdf" }
  ],
  "created_at": "2025-01-15T10:30:00Z",
  "created_by": "Ada Lovelace",
  "updated_at": "2025-01-16T14:22:00Z",
  "updated_by": "Grace Hopper"
}
```

詳細のレスポンスには、[一覧のレスポンス](#list)のフィールドがすべて含まれ、さらに次のフィールドが加わります。

| フィールド                  | 型       | 説明                                                                                                                                  |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `objective`            | string  | 受講者が達成すべきこと                                                                                                                         |
| `context`              | string  | デジタルヒューマンに伝える場面設定                                                                                                                   |
| `personality`          | string  | デジタルヒューマンの性格の説明                                                                                                                     |
| `personality_location` | string  | 場面の所在地                                                                                                                              |
| `personality_type`     | string  | デジタルヒューマンが演じる役割の類型                                                                                                                  |
| `generated_prompt`     | string  | トレーニングの各項目から組み立てられた、セッションで使うプロンプト全文                                                                                                 |
| `prompt_summary`       | string  | 生成されたプロンプトの要約                                                                                                                       |
| `summarized_document`  | string  | 添付資料の要約。資料が無い場合は `null`                                                                                                             |
| `document_description` | string  | 添付資料の説明。資料が無い場合は `null`                                                                                                             |
| `organization_id`      | string  | 組織 ID（例: `org_abc123`）。UUID ではなく組織の識別子です                                                                                            |
| `prompt_only_mode`     | boolean | `true` の場合、トレーニングは `generated_prompt` だけで動作し、人物設定の各項目は使われません                                                                        |
| `documents`            | array   | 添付資料（`id`・`file_name`）。無い場合は `null`                                                                                                 |
| `questions`            | array   | 採点される質問。`TECHNICAL_ACUMEN` のトレーニングのみ（[質問オブジェクト](#question-object)を参照）。ほかの種別ではフィールドごと含まれません                                          |
| `answer_clear_mode`    | string  | `ALLOWED` または `DISALLOWED`。`TECHNICAL_ACUMEN` のトレーニングで `DISALLOWED` の場合、受講者の「クリア」ボタンが表示されず、最初に声で答えた内容が確定します。ほかの種別では `ALLOWED` が返ります |
| `created_by`           | string  | トレーニングを作成した人の表示名                                                                                                                    |
| `updated_by`           | string  | 最後に編集した人の表示名                                                                                                                        |

詳細のレスポンスの `assessments` には、一覧のような `id` と `title` だけでなく、評価基準の詳しい項目が入ります。

| フィールド            | 型             | 説明                                                 |
| ---------------- | ------------- | -------------------------------------------------- |
| `id`             | string (UUID) | 評価基準の ID                                           |
| `title`          | string        | 評価基準の名前                                            |
| `description`    | string        | 何を評価するか                                            |
| `criteria`       | string        | 評価の基準                                              |
| `is_active`      | boolean       | セッションの点数に反映するかどうか                                  |
| `default`        | boolean       | デフォルトの評価基準かどうか                                     |
| `order_position` | integer       | 表示順                                                |
| `weight`         | integer       | トレーニング全体の点数への相対的な寄与度。評価基準に重み付けをしていないトレーニングでは含まれません |

`persona_config` には、[デジタルヒューマンの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-digital-humans)と同じ形のオブジェクトが入ります（上の例では `id` のみを表示しています）。

#### 質問オブジェクト <a href="#question-object" id="question-object"></a>

`TECHNICAL_ACUMEN` のトレーニングにだけ含まれます。1件が、採点される質問1問です。

```json
{
  "id": "q1a2b3c4-d5e6-7890-abcd-ef1234567890",
  "question": "Which two compliance standards apply to this account?",
  "answer_criteria": "Names both SOC 2 and ISO 27001",
  "weight": 2,
  "order_position": 1,
  "resource_label": "Compliance standards overview",
  "resource_url": "https://example.com/compliance-overview",
  "time_limit_seconds": 90
}
```

| フィールド                | 型             | 説明                                                                          |
| -------------------- | ------------- | --------------------------------------------------------------------------- |
| `id`                 | string (UUID) | 質問 ID                                                                       |
| `question`           | string        | 質問文                                                                         |
| `answer_criteria`    | string        | 正答に含まれるべき内容                                                                 |
| `weight`             | integer       | セッションの点数への相対的な寄与度。重み付けが無い場合は含まれません                                          |
| `order_position`     | integer       | トレーニング内での作成順                                                                |
| `resource_label`     | string        | 作成者が質問に付けた参考リンクの表示文字列（最大100文字）。リンクが無い場合は含まれません                              |
| `resource_url`       | string        | その参考リンクの URL（`http`/`https` の絶対 URL、最大2,048文字）。`resource_label` と必ず一緒に含まれます |
| `time_limit_seconds` | integer       | この質問の回答制限時間（秒）。`10`〜`7200`。時間切れになると、その時点までの回答が提出・採点されます。制限が無い場合は含まれません      |

### エラー

| コード   | 原因                                                                               |
| ----- | -------------------------------------------------------------------------------- |
| `401` | APIキーが無い、または無効                                                                   |
| `404` | トレーニングが見つからない。非公開の練習用トレーニング（`PRACTICE`）も、所有者以外には `404` になります                     |
| `429` | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

***

## ロールプレイシナリオを作成する <a href="#create-role-play" id="create-role-play"></a>

お客様が用意した内容から、会話型のトレーニングを作成します。[AI で生成する](#generate)場合と異なり、自動で補われる内容はありません。システムプロンプトはお客様が書き、そのまま保存・使用されます。

```
POST /immersive-training/role-play
```

### 作成されるトレーニングの種類

[AI で生成する](#generate)場合と同じく、作成されるトレーニングの種類は `user_email` だけで決まります。リクエストのほかの項目では変わりません。

| `user_email` | 作成されるもの                                             | 閲覧できる人       | 公開状態                            |
| ------------ | --------------------------------------------------- | ------------ | ------------------------------- |
| **指定しない**    | 組織全体向けのロールプレイシナリオ（`scenario_type: ROLE_PLAY`）       | 組織の全員        | `is_published` で指定（既定は `false`） |
| **指定する**     | そのメンバーが所有する非公開の練習用トレーニング（`scenario_type: PRACTICE`） | **そのメンバーだけ** | 常に公開済み                          |

{% hint style="success" %}
**どちらの作成方法を使うか**\
簡単な説明文から内容を作ってほしい場合は、[AI で生成する](#generate)を使います。\
トレーニングの内容がすでにお客様のシステムにあり、そのとおりに再現したい場合は、このエンドポイントを使います。
{% endhint %}

### 事前に用意するもの

* 学習ドメインの ID。[学習ドメインの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-learning-domains)で確認できます。
* デジタルヒューマンの ID。[デジタルヒューマンの一覧を取得する](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md#list-digital-humans)で確認できます。
* **非公開の練習用トレーニングを作る場合のみ:** 組織で練習モードが有効になっていること、および組織の**有効なメンバー**のメールアドレス。

### リクエストボディ

| フィールド                      | 型                      | 必須  | 説明                                                                                                                |
| -------------------------- | ---------------------- | --- | ----------------------------------------------------------------------------------------------------------------- |
| `name`                     | string                 | はい  | トレーニング名。最大255文字                                                                                                   |
| `learning_domain_id`       | string (UUID)          | はい  | トレーニングが属する学習ドメイン                                                                                                  |
| `persona_config_id`        | string (UUID)          | はい  | 相手役を演じるデジタルヒューマン                                                                                                  |
| `system_prompt`            | string                 | はい  | デジタルヒューマンが従う指示。**そのまま**使われます。最大100,000文字                                                                          |
| `user_email`               | string（email）          | いいえ | 組織の有効なメンバー。指定すると、そのメンバー所有の非公開の練習用トレーニングを作成します。指定しないと、組織全体向けのロールプレイシナリオを作成します。最大254文字                              |
| `participant_instructions` | string                 | いいえ | 開始前に受講者に表示される説明。最大50,000文字                                                                                        |
| `personality_name`         | string                 | いいえ | デジタルヒューマンが演じる人物の名前。最大255文字                                                                                        |
| `personality_role`         | string                 | いいえ | デジタルヒューマンが演じる人物の役職・役割。最大255文字                                                                                     |
| `personality_location`     | string                 | いいえ | デジタルヒューマンの所在地。最大255文字                                                                                             |
| `locales`                  | string                 | いいえ | 言語（ロケール）を**コロン**区切りで指定します。例: `en-US`、`en-US:fr-FR`、`ja-JP`、`ja-JP:en-US`。最大50文字。`ja` だけではエラーになります。指定しないと英語で実施されます |
| `is_published`             | boolean                | いいえ | 既定は `false` で、下書きとして作成されます。練習用トレーニングは常に公開済みです                                                                     |
| `time_limit_minutes`       | integer                | いいえ | セッションの制限時間（分）。`1`〜`120`。指定しないと制限なし                                                                                |
| `max_attempts`             | integer                | いいえ | 受講回数の上限。`1`〜`99`。指定しないと無制限                                                                                        |
| `endorsement_threshold`    | integer                | いいえ | 合格認定に必要な点数（%）。`1`〜`100`。組織全体向けの場合のみ                                                                               |
| `tags`                     | array of string (UUID) | いいえ | タグ。最大50件。組織全体向けの場合のみ                                                                                              |
| `teams`                    | array of string (UUID) | いいえ | トレーニングを割り当てるチーム。最大50件。組織全体向けの場合のみ                                                                                 |
| `assessments`              | array                  | いいえ | 設定する既存の評価基準。最大50件（[評価基準の指定オブジェクト](#assessment-object)を参照）                                                         |
| `new_assessments`          | array                  | いいえ | 新しく作成して設定する評価基準。最大50件（[新しい評価基準オブジェクト](#new-assessment-object)を参照）                                                 |

{% hint style="warning" %}
**人物設定の項目は、表示用の情報です。指示ではありません。**\
`personality_name`・`personality_role`・`personality_location` は、トレーニング一覧やセッション画面での表示に使われます。`system_prompt` には**追加されません**。デジタルヒューマンに知っておいてほしいことは、すべて `system_prompt` 自体に書いてください。
{% endhint %}

{% hint style="warning" %}
**このエンドポイントは、定義されていないフィールドを受け付けません。**\
定義されていないフィールドが含まれていると、無視せずに `400` を返します。フィールド名のつづり間違いが見過ごされることはありません。Q\&Aシナリオ用のフィールド（`questions` など）を送った場合も `400` です。\
`prompt_summary` も受け付けません（下記のとおり自動で作成されます）。
{% endhint %}

```json
{
  "name": "Renewal call with a sceptical buyer",
  "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "persona_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "system_prompt": "You are Dana Whitfield, operations lead at Harrow Logistics. You are sceptical about renewing because a competitor undercut the quote by 20%. Push back on price and warm up only if the participant quantifies downtime savings.",
  "participant_instructions": "You have ten minutes to save the renewal.",
  "personality_name": "Dana Whitfield",
  "personality_role": "Head of Operations",
  "personality_location": "Manchester, UK",
  "locales": "en-GB",
  "is_published": true,
  "time_limit_minutes": 10,
  "endorsement_threshold": 70,
  "tags": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"],
  "new_assessments": [
    {
      "title": "Handles price objections",
      "description": "Responds to the discount demand without conceding immediately",
      "criteria": "Acknowledges the budget pressure, then reframes on total cost rather than unit price",
      "is_active": true,
      "order_position": 0
    }
  ]
}
```

### レスポンス

**201 Created** — 作成されたトレーニングを、[トレーニングを取得する](#get)と同じ形で返します。

{% hint style="success" %}
**`prompt_summary` は、レスポンスの少し後に作成されます。**\
`system_prompt` の短い要約が、トレーニング一覧とセッション後のコーチングフィードバックのために自動で作成されます。作成はバックグラウンドで行われるため、このレスポンスでは空です。後で[トレーニングを取得する](#get)を呼び出すと入っています。お客様が設定できる項目ではありません。
{% endhint %}

### エラー

| コード   | `error_code`           | 原因                                                                               |
| ----- | ---------------------- | -------------------------------------------------------------------------------- |
| `400` | `invalid_request_body` | JSON の形式が正しくない、またはこのエンドポイントで定義されていないフィールド名が含まれている                                |
| `400` | `validation_failed`    | いずれかのフィールドが検証に失敗した、または `locales` に対応していないロケールが含まれている                             |
| `401` | —                      | APIキーが無い、または無効                                                                   |
| `404` | `user_not_in_org`      | `user_email` が組織の有効なメンバーではない                                                     |
| `404` | `validation_failed`    | `tags` に組織のものではないタグが含まれている                                                       |
| `404` | —                      | `learning_domain_id` または `persona_config_id` が組織で使えない                            |
| `413` | `invalid_request_body` | リクエストボディが512KBを超えている                                                             |
| `429` | —                      | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/role-play" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Renewal call with a sceptical buyer",
    "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "persona_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "system_prompt": "You are Dana Whitfield, operations lead at Harrow Logistics...",
    "personality_name": "Dana Whitfield",
    "locales": "en-GB"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    f"{BASE_URL}/immersive-training/role-play",
    headers=headers,
    json={
        "name": "Renewal call with a sceptical buyer",
        "learning_domain_id": learning_domain_id,
        "persona_config_id": persona_config_id,
        "system_prompt": "You are Dana Whitfield, operations lead at Harrow Logistics...",
        "personality_name": "Dana Whitfield",
        "locales": "en-GB",
    },
)
training = response.json()
print(training["id"])
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/immersive-training/role-play`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Renewal call with a sceptical buyer',
    learning_domain_id: learningDomainId,
    persona_config_id: personaConfigId,
    system_prompt: 'You are Dana Whitfield, operations lead at Harrow Logistics...',
    personality_name: 'Dana Whitfield',
    locales: 'en-GB'
  })
});
const training = await response.json();
```

{% endtab %}
{% endtabs %}

#### 評価基準の指定オブジェクト <a href="#assessment-object" id="assessment-object"></a>

組織の評価基準のライブラリにすでにある評価基準を設定します。

| フィールド            | 型             | 必須  | 説明                    |
| ---------------- | ------------- | --- | --------------------- |
| `id`             | string (UUID) | はい  | 設定する評価基準              |
| `is_active`      | boolean       | いいえ | セッションの点数に反映するかどうか     |
| `weight`         | integer       | いいえ | 点数への相対的な寄与度。`0`〜`100` |
| `order_position` | integer       | いいえ | トレーニング内での表示順。`0` 以上   |

#### 新しい評価基準オブジェクト <a href="#new-assessment-object" id="new-assessment-object"></a>

評価基準を新しく作成して設定します。画面で作成した評価基準と同じく、組織で共有している評価基準のライブラリにも追加されます。

| フィールド            | 型       | 必須  | 説明                                             |
| ---------------- | ------- | --- | ---------------------------------------------- |
| `title`          | string  | はい  | 最大255文字                                        |
| `description`    | string  | はい  | 何を評価するか。最大50,000文字                             |
| `criteria`       | string  | はい  | よい対応とはどのようなものか。最大50,000文字                      |
| `is_active`      | boolean | いいえ | セッションの点数に反映するかどうか                              |
| `weight`         | integer | いいえ | 点数への相対的な寄与度。`0`〜`100`                          |
| `order_position` | integer | いいえ | トレーニング内での表示順。`0` 以上                            |
| `resource_label` | string  | いいえ | フィードバックと一緒に表示する参考リンクの表示文字列。最大100文字             |
| `resource_url`   | string  | いいえ | その参考リンクの URL（`http`/`https` の絶対 URL）。最大2,048文字 |

***

## ロールプレイシナリオを更新する <a href="#update-role-play" id="update-role-play"></a>

既存のロールプレイシナリオ、または非公開の練習用トレーニングの内容を変更します。

```
PUT /immersive-training/role-play/{immersiveTrainingID}
```

### パスパラメーター

| パラメーター                | 型             | 説明         |
| --------------------- | ------------- | ---------- |
| `immersiveTrainingID` | string (UUID) | トレーニングの ID |

### リクエストボディ

すべてのフィールドは省略可能で、**省略したフィールドは変更されません**。1項目だけ変える場合は、その1項目だけを送ります。

```json
{ "is_published": false }
```

受け付けるフィールドは[ロールプレイシナリオを作成する](#create-role-play)と同じです。ただし `user_email` は受け付けません。トレーニングの種類（`scenario_type`）は作成時に決まり、変更できないためです。

| 動作                                                         | 対象のフィールド                                                                                    |
| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| 新しい値を送ると置き換え、省略すると現在の値のまま                                  | すべての文字列フィールド                                                                                |
| `0` を送ると制限を解除、省略すると現在の値のまま                                 | `endorsement_threshold`（`0`〜`100`）、`time_limit_minutes`（`0`〜`120`）、`max_attempts`（`0`〜`99`） |
| リストを送ると割り当て全体を置き換え、`[]` で解除、省略すると現在のまま                     | `tags`、`teams`                                                                              |
| リストを送ると設定全体を置き換え。`[]` は**受け付けません**（評価基準の無いトレーニングは採点できないため） | `assessments`（1〜50件）                                                                        |
| 新しく作成して設定する評価基準                                            | `new_assessments`（最大50件）                                                                    |

{% hint style="success" %}
**`system_prompt` を変更すると、`prompt_summary` が作り直されます。**\
作成時と同じく、新しい要約はバックグラウンドで作成されます。そのため、このレスポンスには以前の要約が入っています。`system_prompt` を省略した場合は、どちらも変更されません。
{% endhint %}

すでに添付されている資料はそのまま残ります。このエンドポイントで変更できるのは項目の値だけで、ファイルのアップロードはできません。

### レスポンス

**200 OK** — 更新後のトレーニングを、[トレーニングを取得する](#get)と同じ形で返します。

### エラー

[ロールプレイシナリオを作成する](#create-role-play)のエラーに加えて、次のエラーがあります。

| コード   | `error_code`        | 原因                                                                                          |
| ----- | ------------------- | ------------------------------------------------------------------------------------------- |
| `400` | `validation_failed` | `immersiveTrainingID` が UUID ではない、または `assessments: []` を送った                                |
| `404` | —                   | 組織にその ID のトレーニングが無い、**または** その ID がQ\&Aシナリオのもの。Q\&Aシナリオは[Q\&Aシナリオを更新する](#update-qa)を使ってください |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X PUT \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/role-play/{trainingID}" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"is_published": true, "time_limit_minutes": 15}'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.put(
    f"{BASE_URL}/immersive-training/role-play/{training_id}",
    headers=headers,
    json={"is_published": True, "time_limit_minutes": 15},
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/immersive-training/role-play/${trainingId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ is_published: true, time_limit_minutes: 15 })
});
```

{% endtab %}
{% endtabs %}

***

## Q\&Aシナリオを作成する <a href="#create-qa" id="create-qa"></a>

質問の一覧（質問バンク）から、音声で答えるQ\&Aシナリオを作成します。デジタルヒューマンが質問を読み上げ、受講者の回答は質問ごとの基準で採点されます。

```
POST /immersive-training/qa
```

作成されたトレーニングは `scenario_type: TECHNICAL_ACUMEN` として保存され、[トレーニングを取得する](#get)でもこの値が返ります。

### リクエストボディ

| フィールド                      | 型                      | 必須  | 説明                                                                                     |
| -------------------------- | ---------------------- | --- | -------------------------------------------------------------------------------------- |
| `name`                     | string                 | はい  | トレーニング名。最大255文字                                                                        |
| `learning_domain_id`       | string (UUID)          | はい  | トレーニングが属する学習ドメイン                                                                       |
| `questions`                | array                  | はい  | 質問バンク。1〜200件（[質問の入力オブジェクト](#question-input-object)を参照）                                 |
| `persona_config_id`        | string (UUID)          | いいえ | 質問を読み上げるデジタルヒューマン                                                                      |
| `participant_instructions` | string                 | いいえ | 開始前に受講者に表示される説明。最大50,000文字                                                             |
| `question_ordering`        | string                 | いいえ | 出題順。`SEQUENTIAL`（既定）または `RANDOM`                                                       |
| `questions_per_session`    | integer                | いいえ | 1回のセッションで出題する質問数（1以上）。指定しないと全問を出題します                                                   |
| `answer_clear_mode`        | string                 | いいえ | `ALLOWED`（既定）または `DISALLOWED`。`DISALLOWED` にすると受講者の「クリア」ボタンが表示されず、各質問に最初に声で答えた内容が確定します |
| `locales`                  | string                 | いいえ | 言語（ロケール）を**コロン**区切りで指定します。例: `en-US`、`en-US:fr-FR`、`ja-JP`。最大50文字。`ja` だけではエラーになります    |
| `is_published`             | boolean                | いいえ | 既定は `false` で、下書きとして作成されます                                                             |
| `time_limit_minutes`       | integer                | いいえ | セッションの制限時間（分）。`1`〜`120`                                                                |
| `max_attempts`             | integer                | いいえ | 受講回数の上限。`1`〜`99`                                                                       |
| `endorsement_threshold`    | integer                | いいえ | 合格認定に必要な点数（%）。`1`〜`100`                                                                |
| `tags`                     | array of string (UUID) | いいえ | タグ。最大50件                                                                               |
| `teams`                    | array of string (UUID) | いいえ | トレーニングを割り当てるチーム。最大50件                                                                  |

{% hint style="warning" %}
**Q\&Aシナリオには会話がありません。**\
そのため、`system_prompt`、人物設定の項目、`assessments` は受け付けません（採点には質問と各質問の `answer_criteria` が使われます）。また、Q\&Aシナリオが特定のメンバーだけの非公開になることはないため、`user_email` も受け付けません。これらを送ると `400` になります。\
定義されていないフィールドを送った場合も `400` です。
{% endhint %}

```json
{
  "name": "Network fundamentals",
  "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "persona_config_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "participant_instructions": "Answer each question aloud.",
  "question_ordering": "RANDOM",
  "questions_per_session": 5,
  "questions": [
    {
      "question": "Which OSI layer handles routing?",
      "answer_criteria": "Layer 3, the network layer",
      "weight": 50,
      "order_position": 0
    },
    {
      "question": "What is our support SLA?",
      "answer_criteria": "99.9% uptime with a four-hour response target",
      "weight": 50,
      "order_position": 1
    }
  ],
  "locales": "en-GB",
  "is_published": true
}
```

#### 質問の入力オブジェクト <a href="#question-input-object" id="question-input-object"></a>

| フィールド                | 型       | 必須  | 説明                                                                               |
| -------------------- | ------- | --- | -------------------------------------------------------------------------------- |
| `question`           | string  | はい  | 質問文。最大50,000文字                                                                   |
| `answer_criteria`    | string  | はい  | 正答に含まれるべき内容。最大50,000文字                                                           |
| `weight`             | integer | いいえ | セッションの点数への相対的な寄与度。`0`〜`100`                                                      |
| `order_position`     | integer | いいえ | トレーニング内での作成順。`0` 以上                                                              |
| `time_limit_seconds` | integer | いいえ | この質問の回答制限時間（秒）。`10`〜`7200`。指定しないと制限なし。更新時は質問バンク全体が置き換わるため、更新で省略すると以前に設定した制限は消えます |

### レスポンス

**201 Created** — 作成されたトレーニングを、[トレーニングを取得する](#get)と同じ形で返します。

### エラー

| コード   | `error_code`           | 原因                                                                               |
| ----- | ---------------------- | -------------------------------------------------------------------------------- |
| `400` | `invalid_request_body` | JSON の形式が正しくない、またはこのエンドポイントで定義されていないフィールド名が含まれている                                |
| `400` | `validation_failed`    | いずれかのフィールドが検証に失敗した、`questions` が空、または `locales` に対応していないロケールが含まれている              |
| `401` | —                      | APIキーが無い、または無効                                                                   |
| `404` | `validation_failed`    | `tags` に組織のものではないタグが含まれている                                                       |
| `404` | —                      | `learning_domain_id` または `persona_config_id` が組織で使えない                            |
| `413` | `invalid_request_body` | リクエストボディが512KBを超えている                                                             |
| `429` | —                      | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/qa" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Network fundamentals",
    "learning_domain_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
    "questions": [
      {"question": "Which OSI layer handles routing?", "answer_criteria": "Layer 3, the network layer", "order_position": 0}
    ]
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    f"{BASE_URL}/immersive-training/qa",
    headers=headers,
    json={
        "name": "Network fundamentals",
        "learning_domain_id": learning_domain_id,
        "questions": [
            {
                "question": "Which OSI layer handles routing?",
                "answer_criteria": "Layer 3, the network layer",
                "order_position": 0,
            }
        ],
    },
)
training = response.json()
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/immersive-training/qa`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Network fundamentals',
    learning_domain_id: learningDomainId,
    questions: [
      { question: 'Which OSI layer handles routing?', answer_criteria: 'Layer 3, the network layer', order_position: 0 }
    ]
  })
});
```

{% endtab %}
{% endtabs %}

***

## Q\&Aシナリオを更新する <a href="#update-qa" id="update-qa"></a>

既存のQ\&Aシナリオの内容を変更します。

```
PUT /immersive-training/qa/{immersiveTrainingID}
```

### パスパラメーター

| パラメーター                | 型             | 説明         |
| --------------------- | ------------- | ---------- |
| `immersiveTrainingID` | string (UUID) | トレーニングの ID |

### リクエストボディ

すべてのフィールドは省略可能で、**省略したフィールドは変更されません**。受け付けるフィールドは[Q\&Aシナリオを作成する](#create-qa)と同じです（`answer_clear_mode` も、省略すると現在の値のままです）。

| 動作                                     | 対象のフィールド                                                                                    |
| -------------------------------------- | ------------------------------------------------------------------------------------------- |
| 新しい値を送ると置き換え、省略すると現在の値のまま              | すべての文字列フィールド                                                                                |
| `0` を送ると制限を解除、省略すると現在の値のまま             | `endorsement_threshold`（`0`〜`100`）、`time_limit_minutes`（`0`〜`120`）、`max_attempts`（`0`〜`99`） |
| リストを送ると割り当て全体を置き換え、`[]` で解除、省略すると現在のまま | `tags`、`teams`                                                                              |
| リストを送ると質問バンク**全体**を置き換え、省略すると現在のまま     | `questions`（最大200件）                                                                         |

{% hint style="warning" %}
`questions` を送ると質問バンク全体が置き換わります。各質問の `time_limit_seconds` も、送らなかった質問では制限が消えます。
{% endhint %}

### レスポンス

**200 OK** — 更新後のトレーニングを、[トレーニングを取得する](#get)と同じ形で返します。

### エラー

[Q\&Aシナリオを作成する](#create-qa)のエラーに加えて、次のエラーがあります。

| コード   | `error_code`        | 原因                                                                                                          |
| ----- | ------------------- | ----------------------------------------------------------------------------------------------------------- |
| `400` | `validation_failed` | `immersiveTrainingID` が UUID ではない                                                                           |
| `404` | —                   | 組織にその ID のトレーニングが無い、**または** その ID がロールプレイシナリオか練習用トレーニングのもの。それらは[ロールプレイシナリオを更新する](#update-role-play)を使ってください |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X PUT \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/qa/{trainingID}" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"question_ordering": "RANDOM", "questions_per_session": 5}'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.put(
    f"{BASE_URL}/immersive-training/qa/{training_id}",
    headers=headers,
    json={"question_ordering": "RANDOM", "questions_per_session": 5},
)
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/immersive-training/qa/${trainingId}`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({ question_ordering: 'RANDOM', questions_per_session: 5 })
});
```

{% endtab %}
{% endtabs %}

***

## トレーニングを削除する <a href="#delete" id="delete"></a>

トレーニングを削除します（論理削除）。

```
DELETE /immersive-training/{immersiveTrainingID}
```

### パスパラメーター

| パラメーター                | 型             | 説明         |
| --------------------- | ------------- | ---------- |
| `immersiveTrainingID` | string (UUID) | トレーニングの ID |

### レスポンス

**204 No Content** — 削除に成功しました。

### エラー

| コード   | 原因                                                                               |
| ----- | -------------------------------------------------------------------------------- |
| `401` | APIキーが無い、または無効                                                                   |
| `404` | トレーニングが見つからない                                                                    |
| `429` | レート制限を超えた。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

### 例

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X DELETE \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/immersive-training/{trainingID}" \
  -H "Authorization: Bearer your-api-key"
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.delete(
    f"{BASE_URL}/immersive-training/{training_id}",
    headers=headers
)
# 204 = 成功
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
await fetch(`${BASE_URL}/immersive-training/${trainingId}`, {
  method: 'DELETE',
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
```

{% endtab %}
{% endtabs %}

## 関連ページ

* [ロールプレイシナリオを作成する（画面での操作）](https://docs.digitalhumans.jp/itp-guide/create-trainings.md)
* [Q\&Aシナリオを作成する（画面での操作）](https://docs.digitalhumans.jp/itp-guide/create-trainings/qa-scenarios.md)
* [評価基準を設定する](https://docs.digitalhumans.jp/itp-guide/create-trainings/assessments.md)
* [参照データ](https://docs.digitalhumans.jp/itp-guide/api/reference-data.md)
* [データのエクスポート](https://docs.digitalhumans.jp/itp-guide/api/data-export.md)
