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

# 参照データ

学習ドメイン、デジタルヒューマン、デフォルトの評価基準、タグを取得します。いずれも読み取り専用のエンドポイントです。[トレーニング](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md)のレスポンスに出てくる ID の中身を調べたり、トレーニングの一覧の絞り込みや作成に使う ID を確認したりするのに使います。

{% hint style="info" %}
**結果が0件のとき**\
返すものが無い場合、これらのエンドポイントは空の配列（`[]`）ではなく `null` を返します。お客様のクライアントでは、`null` を空のリストとして扱ってください。
{% endhint %}

## エンドポイント一覧

| メソッド  | エンドポイント                | 内容                                          |
| ----- | ---------------------- | ------------------------------------------- |
| `GET` | `/learning-domains`    | [学習ドメインの一覧を取得する](#list-learning-domains)    |
| `GET` | `/use-cases`           | [ユースケースの一覧を取得する（廃止予定）](#list-use-cases)     |
| `GET` | `/persona-config`      | [デジタルヒューマンの一覧を取得する](#list-digital-humans)   |
| `GET` | `/default-assessments` | [デフォルトの評価基準を取得する](#get-default-assessments) |
| `GET` | `/tags`                | [タグの一覧を取得する](#list-tags)                    |

すべてのパスは、ベース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) をご覧ください。

### 共通のエラー

本ページのエンドポイントは、いずれも次のエラーを返すことがあります。どちらも本文の内容は `message` ではなく `error` に入ります。

| コード   | 原因                                                                                                                  |
| ----- | ------------------------------------------------------------------------------------------------------------------- |
| `401` | APIキーが無い、形式が正しくない、または URL の組織のものではない                                                                                |
| `429` | レート制限を超えた。`Retry-After` ヘッダーに再試行までの待ち秒数が入ります。[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)を参照 |

***

## 学習ドメインの一覧を取得する <a href="#list-learning-domains" id="list-learning-domains"></a>

組織で使える学習ドメインをすべて取得します。並び順は `order_position`、次に `title` の順です。ページ分割はありません。

```
GET /learning-domains
```

### レスポンス

**200 OK:**

```json
[
  {
    "id": "d4e5f6a7-b890-1234-defg-456789012345",
    "title": "Sales Discovery",
    "description": "Practice discovery conversations with potential customers",
    "organization_id": "org_abc123",
    "order_position": 1,
    "last_updated": "2025-01-10T08:00:00Z"
  },
  {
    "id": "e5f6a7b8-9012-3456-efgh-567890123456",
    "title": "Objection Handling",
    "description": "Practice handling common customer objections",
    "organization_id": "org_abc123",
    "order_position": 2,
    "last_updated": "2025-01-12T14:30:00Z"
  }
]
```

| フィールド             | 型                 | 説明                                                                                      |
| ----------------- | ----------------- | --------------------------------------------------------------------------------------- |
| `id`              | string (UUID)     | 学習ドメイン ID。トレーニングの `learning_domain_id` と同じ値で、トレーニングの一覧を絞り込む `learning_domain_id` にも使えます |
| `title`           | string            | 学習ドメインの名前                                                                               |
| `description`     | string            | 学習ドメインの説明                                                                               |
| `organization_id` | string            | 組織 ID（例: `org_abc123`）。UUID ではなく組織の識別子です                                                |
| `order_position`  | integer           | 表示順                                                                                     |
| `last_updated`    | string (ISO 8601) | 最終更新日時。値が無い場合は `null`                                                                   |

組織に学習ドメインが1件も無い場合は、`[]` ではなく `null` が返ります。

### 例

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

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(f"{BASE_URL}/learning-domains", headers=headers)
domains = response.json() or []
for d in domains:
    print(f"{d['title']}: {d['id']}")
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/learning-domains`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const domains = (await response.json()) ?? [];
```

{% endtab %}
{% endtabs %}

***

## ユースケースの一覧を取得する（廃止予定） <a href="#list-use-cases" id="list-use-cases"></a>

{% hint style="warning" %}
**廃止予定です。新しい実装では使わないでください。**\
「Use Case（ユースケース）」は「Learning Domain（学習ドメイン）」に名称が変わりました。`GET /use-cases` は、すでにデータを返しません。代わりに [`GET /learning-domains`](#list-learning-domains) を呼び出してください。\
今後削除される予定です。削除の時期については、[弊社にお問い合わせください](https://www.digitalhumans.com/jp/contact)。
{% endhint %}

```
GET /use-cases
```

### レスポンス

**301 Moved Permanently** — ユースケースのデータは返らず、レスポンスの本文は**空**です。

`Location` ヘッダーには**相対参照** `learning-domains` が入り、リクエストした URL を基準に解決されます（クエリ文字列はそのまま引き継がれます）。

```
HTTP/1.1 301 Moved Permanently
Location: learning-domains
```

HTTP クライアントがリダイレクトをたどるように設定してください。`curl` の場合は `-L` を付けます。

***

## デジタルヒューマンの一覧を取得する <a href="#list-digital-humans" id="list-digital-humans"></a>

トレーニングに設定できるデジタルヒューマンを取得します。

```
GET /persona-config
```

### レスポンス

**200 OK:**

```json
[
  {
    "id": "f6a7b890-1234-5678-ghij-678901234567",
    "share_id": "share-uuid",
    "avatar_url": "https://cdn.uneeq.io/avatars/sophie.png",
    "short_description": "Friendly enterprise buyer",
    "purpose": "ALL",
    "gender": "FEMALE",
    "is_default_ai_buddy": true
  },
  {
    "id": "a7b89012-3456-7890-hijk-789012345678",
    "share_id": "share-uuid-2",
    "avatar_url": "https://cdn.uneeq.io/avatars/marcus.png",
    "purpose": "AI_BUDDY",
    "gender": "MALE",
    "is_default_ai_buddy": false
  }
]
```

| フィールド                   | 型             | 説明                                                                                                 |
| ----------------------- | ------------- | -------------------------------------------------------------------------------------------------- |
| `id`                    | string (UUID) | デジタルヒューマン ID。トレーニングの `persona_config` オブジェクト内の `id` と同じ値で、トレーニングの作成時に `persona_config_id` として指定します |
| `share_id`              | string (UUID) | デジタルヒューマンの共有用の識別子                                                                                  |
| `avatar_url`            | string        | アバター画像の URL                                                                                        |
| `short_description`     | string        | 短い説明。設定されていない場合は含まれません                                                                             |
| `purpose`               | string        | `ALL`（どのトレーニングにも使える）または `AI_BUDDY`（AI Buddy との会話専用）                                                |
| `gender`                | string        | `MALE`、`FEMALE`、`NEUTRAL` のいずれか                                                                    |
| `is_default_ai_buddy`   | boolean       | 組織の既定の AI Buddy かどうか                                                                               |
| `custom_animation_tags` | string        | デジタルヒューマンの動き（アニメーション）の指定。設定されていない場合は含まれません                                                         |

使えるデジタルヒューマンが無い場合は、`[]` ではなく `null` が返ります。

{% hint style="info" %}
**上記以外のフィールド**\
このレスポンスには、上記以外のフィールドが含まれることがあります。サポート対象は記載したフィールドだけです。それ以外のフィールドは内部用で、予告なく変更される場合があります。
{% endhint %}

### 例

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

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(f"{BASE_URL}/persona-config", headers=headers)
configs = response.json()
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/persona-config`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const configs = await response.json();
```

{% endtab %}
{% endtabs %}

***

## デフォルトの評価基準を取得する <a href="#get-default-assessments" id="get-default-assessments"></a>

組織のデフォルトの評価基準を取得します。取得した評価基準は、トレーニングの作成時に設定できます（[評価基準の指定オブジェクト](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md#assessment-object)を参照）。

```
GET /default-assessments
```

### レスポンス

**200 OK:**

```json
[
  {
    "id": "b890-1234-5678-ijkl-890123456789",
    "title": "Discovery Skills",
    "description": "Ability to ask effective open-ended questions and uncover customer needs",
    "criteria": "Asks probing questions, listens actively, identifies pain points",
    "default": true,
    "organization_id": "org_abc123",
    "order_position": 1,
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-03-04T09:15:00Z",
    "updated_by": "Grace Hopper",
    "learning_domains": [
      {
        "id": "d4e5f6a7-b890-1234-defg-456789012345",
        "title": "Sales Discovery",
        "description": "Practice discovery conversations with potential customers"
      }
    ]
  },
  {
    "id": "c901-2345-6789-jklm-901234567890",
    "title": "Product Knowledge",
    "description": "Accurate and relevant product information delivery",
    "criteria": "Demonstrates product understanding, positions features as benefits",
    "default": true,
    "organization_id": "org_abc123",
    "order_position": 2,
    "created_at": "2025-01-01T00:00:00Z"
  }
]
```

| フィールド              | 型                 | 説明                                                                                                                                                                  |
| ------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`               | string (UUID)     | 評価基準 ID。トレーニングの `assessments` 配列の各要素の `id` と同じ値です                                                                                                                   |
| `title`            | string            | 評価基準の名前                                                                                                                                                             |
| `description`      | string            | 何を評価するか                                                                                                                                                             |
| `criteria`         | string            | 評価の基準の詳細                                                                                                                                                            |
| `default`          | boolean           | このエンドポイントでは常に `true`（デフォルトの評価基準だけを返すため）                                                                                                                             |
| `organization_id`  | string            | 組織 ID（例: `org_abc123`）。UUID ではなく組織の識別子です                                                                                                                            |
| `order_position`   | integer           | 表示順                                                                                                                                                                 |
| `created_at`       | string (ISO 8601) | 作成日時                                                                                                                                                                |
| `updated_at`       | string (ISO 8601) | 最終更新日時。一度も編集されていない場合は含まれません                                                                                                                                         |
| `updated_by`       | string            | 最後に編集した人の表示名                                                                                                                                                        |
| `learning_domains` | array             | この評価基準が設定されている学習ドメイン。各要素は `id`・`title`・`description` を持ちます。どの学習ドメインにも設定されていない場合は含まれません。学習ドメインの全項目を読むには [`GET /learning-domains`](#list-learning-domains) を呼び出してください |

### 例

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

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(f"{BASE_URL}/default-assessments", headers=headers)
assessments = response.json()
for a in assessments:
    print(f"{a['title']}: {a['id']}")
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/default-assessments`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const assessments = await response.json();
```

{% endtab %}
{% endtabs %}

***

## タグの一覧を取得する <a href="#list-tags" id="list-tags"></a>

組織のタグをすべて取得します。タグはトレーニングの分類に使います。

```
GET /tags
```

`name` の昇順で、最大1,000件を返します。ページ分割はありません。

### レスポンス

**200 OK:**

```json
[
  {
    "id": "d012-3456-7890-klmn-012345678901",
    "name": "Sales",
    "color": "#3b82f6"
  },
  {
    "id": "e123-4567-8901-lmno-123456789012",
    "name": "Onboarding",
    "color": "#22c55e"
  }
]
```

| フィールド   | 型             | 説明                                                      |
| ------- | ------------- | ------------------------------------------------------- |
| `id`    | string (UUID) | タグ ID。トレーニングの一覧を絞り込む `tags` や、トレーニングの作成時の `tags` に指定します |
| `name`  | string        | タグの表示名                                                  |
| `color` | string        | タグの色（16進数のカラーコード）                                       |

### 例

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

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(f"{BASE_URL}/tags", headers=headers)
tags = response.json()
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/tags`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const tags = await response.json();
```

{% endtab %}
{% endtabs %}

## 関連ページ

* [トレーニング](https://docs.digitalhumans.jp/itp-guide/api/immersive-training.md)
* [用語集](https://docs.digitalhumans.jp/itp-guide/about/glossary.md)
