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

# チーム

チームの作成・変更・削除と、チームへのシナリオの割り当てを API で行えます。チームにユーザーを追加・削除する操作は「[チームメンバー](https://docs.digitalhumans.jp/itp-guide/api/team-members.md)」をご覧ください。画面での操作は「[チームとシナリオの割り当て](https://docs.digitalhumans.jp/itp-guide/initial-setup/teams.md)」をご覧ください。

コード例の `BASE_URL`・`headers`・`API_KEY` は、「[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)」のコード例で定義したものです。

## エンドポイント一覧

| メソッド     | エンドポイント                            | 内容                                           |
| -------- | ---------------------------------- | -------------------------------------------- |
| `POST`   | `/teams/create`                    | [チームを作成する](#post-teams-create)               |
| `PUT`    | `/teams/{teamID}`                  | [チームを編集する](#put-teams-teamid)                |
| `DELETE` | `/teams/{teamID}`                  | [チームを削除する](#delete-teams-teamid)             |
| `GET`    | `/teams/page/{page}/limit/{limit}` | [チームを一覧する](#get-teams-page)                  |
| `GET`    | `/teams/{teamID}`                  | [チームを1件取得する](#get-teams-teamid)              |
| `GET`    | `/teams/{teamID}/scenarios`        | [チームのシナリオを取得する](#get-teams-teamid-scenarios) |
| `PUT`    | `/teams/{teamID}/scenarios`        | [チームのシナリオを設定する](#put-teams-teamid-scenarios) |
| `POST`   | `/teams/{teamID}/tags`             | [チームにタグを追加する（廃止予定）](#post-teams-teamid-tags) |
| `DELETE` | `/teams`                           | [チームをまとめて削除する](#delete-teams)                |

すべてのエンドポイントは、APIキーが無効な場合に `401`（ボディは `error` キー）、レート制限を超えた場合に `429` を返します。詳しくは「[認証](https://docs.digitalhumans.jp/itp-guide/api/authentication.md)」「[レート制限](https://docs.digitalhumans.jp/itp-guide/api/rate-limits.md)」をご覧ください。

## チームのオブジェクト <a href="#team-object" id="team-object"></a>

チームを返すエンドポイントは、次の形のオブジェクトを返します。

| フィールド         | 型            | 説明                                       |
| ------------- | ------------ | ---------------------------------------- |
| `id`          | string（UUID） | チーム ID                                   |
| `name`        | string       | チーム名                                     |
| `description` | string       | チームの説明                                   |
| `tags`        | object\[]    | **廃止予定**。常に空の配列です。2027-03-01 に削除されます（下記） |

`tags` の要素（タグのオブジェクト）は `id`（string、UUID）、`name`（string）、`color`（string。例: `#3b82f6`）を持ちます。

{% hint style="warning" %}
**`tags` フィールドは廃止予定です（2027-03-01 に削除）。**\
チームとタグの関連付けは廃止されたため、`tags` は常に空の配列です。互換性のために残されています。チームに何が割り当てられているかは、[`GET /teams/{teamID}/scenarios`](#get-teams-teamid-scenarios) で確認してください。
{% endhint %}

***

## チームを作成する <a href="#post-teams-create" id="post-teams-create"></a>

組織に新しいチームを作成します。

```
POST /teams/create
```

### リクエストボディ

```json
{
  "name": "Sales - West Coast",
  "description": "West Coast sales representatives"
}
```

| フィールド         | 型      | 説明     | 必須 |
| ------------- | ------ | ------ | -- |
| `name`        | string | チーム名   | はい |
| `description` | string | チームの説明 | はい |

### レスポンス

**200 OK**

```json
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "Sales - West Coast",
  "description": "West Coast sales representatives",
  "tags": []
}
```

### エラー

| コード   | 説明                                     |
| ----- | -------------------------------------- |
| `400` | 不正なリクエスト（`name` または `description` が無い） |
| `401` | APIキーが無効                               |
| `409` | 同じ名前のチームが組織内にすでにある                     |
| `429` | レート制限を超えた                              |

{% hint style="info" %}
**チーム名は組織内で一意です。**\
すでに使われている名前でチームを作成すると、`409` とボディ `{"message": "A team with this name already exists for your organization"}` が返ります。[チームを編集する](#put-teams-teamid)で名前を変える場合も同じです。
{% endhint %}

### 例

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

```bash
curl -X POST \
  "https://training.uneeq.io/api/external/v1/organization/{orgID}/teams/create" \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "Sales - West Coast", "description": "West Coast sales reps"}'
```

{% endtab %}

{% tab title="Python" %}

```python
response = requests.post(
    f"{BASE_URL}/teams/create",
    headers=headers,
    json={"name": "Sales - West Coast", "description": "West Coast sales reps"}
)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/teams/create`, {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ name: 'Sales - West Coast', description: 'West Coast sales reps' })
});
const team = await response.json();
```

{% endtab %}
{% endtabs %}

***

## チームを編集する <a href="#put-teams-teamid" id="put-teams-teamid"></a>

既存のチームの名前と説明を変更します。

```
PUT /teams/{teamID}
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### リクエストボディ

```json
{
  "name": "Sales - Pacific Northwest",
  "description": "Updated team description"
}
```

| フィールド         | 型      | 説明       | 必須 |
| ------------- | ------ | -------- | -- |
| `name`        | string | 変更後のチーム名 | はい |
| `description` | string | 変更後の説明   | はい |

### レスポンス

**200 OK**: 変更後のチームのオブジェクトを返します。

### エラー

| コード   | 説明                                     |
| ----- | -------------------------------------- |
| `400` | 不正なリクエスト（`name` または `description` が無い） |
| `401` | APIキーが無効                               |
| `409` | 同じ名前のチームが組織内にすでにある                     |
| `429` | レート制限を超えた                              |

***

## チームを削除する <a href="#delete-teams-teamid" id="delete-teams-teamid"></a>

チームを1つ削除します。

```
DELETE /teams/{teamID}
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### レスポンス

| ステータス            | 内容              |
| ---------------- | --------------- |
| `204 No Content` | 削除に成功。ボディはありません |
| `401`            | APIキーが無効        |
| `404`            | チームが見つからない      |
| `429`            | レート制限を超えた       |

***

## チームを一覧する <a href="#get-teams-page" id="get-teams-page"></a>

組織のチームをページ単位で取得します。

```
GET /teams/page/{page}/limit/{limit}
```

### パスパラメーター

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

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

| パラメーター   | 型      | 説明                                           |
| -------- | ------ | -------------------------------------------- |
| `search` | string | チーム名で検索                                      |
| `tags`   | string | **廃止予定**。無視され、結果は絞り込まれません。2027-03-01 に削除されます |

{% hint style="warning" %}
**クエリパラメーター `tags` は廃止予定です（2027-03-01 に削除）。**\
チームとタグの関連付けは廃止されたため、指定しても無視されます。
{% endhint %}

### レスポンス

**200 OK**

```json
{
  "records": 15,
  "teams": [
    {
      "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "Sales - West Coast",
      "description": "West Coast sales representatives",
      "tags": []
    }
  ]
}
```

| フィールド     | 型         | 説明                            |
| --------- | --------- | ----------------------------- |
| `records` | integer   | 条件に一致したチームの総数                 |
| `teams`   | object\[] | [チームのオブジェクト](#team-object)の配列 |

### 例

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

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

{% endtab %}

{% tab title="Python" %}

```python
response = requests.get(f"{BASE_URL}/teams/page/1/limit/25", headers=headers)
print(response.json())
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const response = await fetch(`${BASE_URL}/teams/page/1/limit/25`, {
  headers: { 'Authorization': `Bearer ${API_KEY}` }
});
const data = await response.json();
```

{% endtab %}
{% endtabs %}

***

## チームを1件取得する <a href="#get-teams-teamid" id="get-teams-teamid"></a>

ID を指定してチームを1件取得します。

```
GET /teams/{teamID}
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### レスポンス

**200 OK**

```json
{
  "id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
  "name": "Sales - West Coast",
  "description": "West Coast sales representatives",
  "tags": []
}
```

| ステータス | 内容         |
| ----- | ---------- |
| `200` | 成功         |
| `401` | APIキーが無効   |
| `404` | チームが見つからない |
| `429` | レート制限を超えた  |

{% hint style="warning" %}
**`tags` は廃止予定で、常に空です（2027-03-01 に削除）。**\
チームとタグの関連付けは廃止されました。このフィールドは互換性のために残されています。チームに何が割り当てられているかは、[`GET /teams/{teamID}/scenarios`](#get-teams-teamid-scenarios) で確認してください。
{% endhint %}

***

## チームのシナリオを取得する <a href="#get-teams-teamid-scenarios" id="get-teams-teamid-scenarios"></a>

チームに割り当てたシナリオを一覧します。これらのシナリオは、チームのメンバーがトレーニングの一覧で「自分に割り当て済み」フィルターを使うと表示されます。

```
GET /teams/{teamID}/scenarios
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### レスポンス

**200 OK**

```json
{
  "scenarios": [
    {
      "id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "name": "Objection Handling",
      "is_published": true,
      "scenario_type": "ROLE_PLAY"
    }
  ]
}
```

| フィールド                       | 型            | 説明                                                                                                                                                          |
| --------------------------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `scenarios[].id`            | string（UUID） | シナリオ ID                                                                                                                                                     |
| `scenarios[].name`          | string       | シナリオ名                                                                                                                                                       |
| `scenarios[].is_published`  | boolean      | 公開されているかどうか                                                                                                                                                 |
| `scenarios[].scenario_type` | string       | シナリオの種類。`ROLE_PLAY`（会話形式のロールプレイ）、`TECHNICAL_ACUMEN`（採点される質問のセット。Q\&Aシナリオ）、`PRACTICE`（作成者本人だけが使う非公開のロールプレイ）。値は今後追加されることがあります。認識できない値はエラーにせず、未対応の種類として扱ってください |

このレスポンスはページングされません。1チームに割り当てられるシナリオは最大 500 件のため、すべてが一度に返ります。

| ステータス | 内容                   |
| ----- | -------------------- |
| `200` | 成功                   |
| `400` | 不正なリクエスト             |
| `401` | APIキーが無効             |
| `403` | チームが存在しない、または別の組織のもの |
| `429` | レート制限を超えた            |

***

## チームのシナリオを設定する <a href="#put-teams-teamid-scenarios" id="put-teams-teamid-scenarios"></a>

チームに割り当てるシナリオの組み合わせを置き換えます。

```
PUT /teams/{teamID}/scenarios
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### リクエストボディ

```json
{
  "assigned_scenario_ids": ["scenario-uuid-1", "scenario-uuid-2"]
}
```

| フィールド                   | 型               | 説明                             | 必須 |
| ----------------------- | --------------- | ------------------------------ | -- |
| `assigned_scenario_ids` | string\[]（UUID） | チームに割り当てるシナリオ ID の全体（最大 500 件） | はい |

{% hint style="warning" %}
**`assigned_scenario_ids` は追加ではなく、チームのシナリオをまるごと置き換えます。**\
現在チームに割り当てられているシナリオのうち、指定しなかったものは割り当てが外れます。毎回、割り当てたいシナリオをすべて指定してください。1件だけ追加するには、[チームのシナリオを取得する](#get-teams-teamid-scenarios)で現在の組み合わせを読み、新しいシナリオを加えて送ります。\
このフィールドは必須で、省略すると `400` になります。すべての割り当てを外すには、明示的に `[]` を送ってください。
{% endhint %}

### レスポンス

| ステータス            | 内容                                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ |
| `204 No Content` | 割り当ての更新に成功。ボディはありません                                                                                               |
| `400`            | 不正なリクエスト（`assigned_scenario_ids` が無い場合など）                                                                          |
| `401`            | APIキーが無効                                                                                                           |
| `403`            | チームが存在しない、または別の組織のもの。または `assigned_scenario_ids` に、お客様の組織のシナリオでないものが含まれる。練習用シナリオ（`PRACTICE`）はチームに割り当てられず、同じく拒否されます |
| `429`            | レート制限を超えた                                                                                                          |

***

## チームにタグを追加する（廃止予定） <a href="#post-teams-teamid-tags" id="post-teams-teamid-tags"></a>

{% hint style="warning" %}
**このエンドポイントは廃止予定です（2027-03-01 に削除）。**\
チームとタグの関連付けは廃止され、タグはシナリオを分類するためだけのものになりました。`POST /teams/{teamID}/tags` はリクエストを検証して `204` を返しますが、何も保存しません。\
チームで使うシナリオを指定するには、[`PUT /teams/{teamID}/scenarios`](#put-teams-teamid-scenarios) でシナリオを直接割り当ててください。
{% endhint %}

```
POST /teams/{teamID}/tags
```

### パスパラメーター

| パラメーター   | 型            | 説明     |
| -------- | ------------ | ------ |
| `teamID` | string（UUID） | チーム ID |

### リクエストボディ

```json
{
  "tags_id": ["tag-uuid-1", "tag-uuid-2"]
}
```

| フィールド     | 型               | 説明                              | 必須  |
| --------- | --------------- | ------------------------------- | --- |
| `tags_id` | string\[]（UUID） | 無視されます。UUID の配列として検証された後、破棄されます | いいえ |

### レスポンス

**204 No Content**: リクエストは受け付けられ、破棄されました。ボディはありません。

レスポンスには、廃止予定を示す標準のヘッダーが付きます。

```
Deprecation: @1788220800
Sunset: Mon, 01 Mar 2027 00:00:00 GMT
Link: <...>; rel="deprecation"; type="text/html"
```

`Link` ヘッダーには、移行先（`PUT /teams/{teamID}/scenarios`）を説明する提供元の英語ドキュメントの URL が入ります。

| ステータス            | 内容                                    |
| ---------------- | ------------------------------------- |
| `204 No Content` | 受け付けて破棄した                             |
| `400`            | 不正なリクエスト（`tags_id` が UUID の配列でない場合など） |
| `401`            | APIキーが無効                              |
| `403`            | チームが存在しない、または別の組織のもの                  |
| `429`            | レート制限を超えた                             |

廃止予定を示すヘッダーは、エラーを含むすべてのレスポンスに付きます。

***

## チームをまとめて削除する <a href="#delete-teams" id="delete-teams"></a>

1回のリクエストで複数のチームを削除します。

```
DELETE /teams
```

### リクエストボディ

```json
{
  "team_ids": ["team-uuid-1", "team-uuid-2"]
}
```

| フィールド      | 型               | 説明             | 必須 |
| ---------- | --------------- | -------------- | -- |
| `team_ids` | string\[]（UUID） | 削除するチーム ID の一覧 | はい |

### レスポンス

| ステータス            | 内容              |
| ---------------- | --------------- |
| `204 No Content` | 削除に成功。ボディはありません |
| `400`            | 不正なリクエスト        |
| `401`            | APIキーが無効        |
| `429`            | レート制限を超えた       |
