# General Translation Platform: タグの作成または更新
URL: https://generaltranslation.com/ja/docs/platform/openapi/reference/project/upsert-tag.mdx
---

title: タグの作成または更新
description: リリース追跡のために、General Translation のファイルバージョンにタグを作成または更新します。タグの作成または更新の API リファレンス。

method: POST
---

ファイルバージョンのセットにタグを作成するか、同じ ID を持つ既存のタグを上書きします。タグを使って、どのファイルバージョンがリリースに含まれるかを示します。

## 概要 [#overview]

```http
POST https://api2.gtx.dev/v2/project/tags/create
```

**権限** `project:files:write` · **レート制限** デフォルト (200/分) 

名前付きタグを特定のファイルバージョンに固定します。ファイル参照 を先に解決するには、[ファイル情報を取得](/docs/platform/openapi/reference/files/file-info) を使用します。

## 仕組み [#how-it-works]

* 各ファイル参照 (`fileId` + `versionId` + `branchId`) は内部のソースファイルに解決され、同じ `tagId` を持つ既存のタグは上書きされます。
* どの参照もソースファイルに解決されない場合、リクエストは `400` を返します。一部の参照のみが解決され、ほかが解決されない場合は、リクエストは `400` を返し、解決されなかったファイル ID を一覧表示します。
* レスポンスでは、タイムスタンプを含む保存済みのタグが返されます。

## リクエスト [#request]

### ヘッダー

| ヘッダー              | 説明                          | 必須  |
| ----------------- | --------------------------- | --- |
| `x-gt-api-key`    | プロジェクトまたは組織の API キー。        | はい  |
| `x-gt-project-id` | プロジェクト ID。組織キーを使用する場合に必須です。 | いいえ |

### 本文

**Content type** `application/json`

| フィールド             | 説明                         | 型          | 任意  | デフォルト |
| ----------------- | -------------------------- | ---------- | --- | ----- |
| `tagId`           | タグ識別子 (1〜255文字) 。          | `string`   | いいえ | —     |
| [`files`](#files) | タグ付けするファイルのバージョン。1つ以上必要です。 | `object[]` | いいえ | —     |
| `message`         | タグに付ける任意のメッセージ (最大255文字) 。 | `string`   | はい  | —     |

#### `files` [#files]

**型** `object[]` · **必須**

各要素は1つのファイルバージョンを参照します。いずれの値も空欄にはできません。

| 項目          | 説明               | 型        | Optional | Default |
| ----------- | ---------------- | -------- | -------- | ------- |
| `fileId`    | 不変のファイル識別子。      | `string` | いいえ      | —       |
| `versionId` | バージョン識別子。        | `string` | いいえ      | —       |
| `branchId`  | ファイルが紐付いているブランチ。 | `string` | いいえ      | —       |

## レスポンス [#response]

**ステータス** `200 OK`

```json title="Response"
{
  "tag": {
    "id": "tag_...",
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "createdAt": "2026-01-01T00:00:00.000Z",
    "updatedAt": "2026-01-01T00:00:00.000Z"
  }
}
```

## エラー [#errors]

| ステータス | 原因                                                     |
| ----- | ------------------------------------------------------ |
| `400` | リクエストボディが無効、対応するソースファイルが存在しない、または一部のファイル参照を解決できませんでした。 |
| `401` | API キーがないか、無効です。                                       |
| `403` | API キーに `project:files:write` がありません。                  |
| `429` | レート制限を超過しました。                                          |

## 例 [#example]

```bash
curl -X POST https://api2.gtx.dev/v2/project/tags/create \
  -H "x-gt-api-key: gtx-api-..." \
  -H "Content-Type: application/json" \
  -d '{
    "tagId": "v1.2.0",
    "message": "Release 1.2.0",
    "files": [
      {
        "fileId": "file_...",
        "versionId": "ver_...",
        "branchId": "br_..."
      }
    ]
  }'
```