# Version tags and notes

Two operations on an already saved version, with no re-upload of the archive: `PATCH` replaces the tag list and the note wholesale, while `tag` adds or removes a single tag. The `manual` and `published` tags protect a version from automatic cleanup.

Storage overview and the endpoint reference — [Source code storage](/docs/source-storage).

## Updating version metadata

`PATCH /v1/apps/:id/sources/:versionId`

Updates the tags and/or note of an existing version without re-uploading the archive. Use it when you need to add a tag or adjust a note after the fact.

### Path parameters

| Parameter | Type | Description |
|----------|-----|----------|
| `id` (path) | UUID | Application identifier. |
| `versionId` (path) | string | Version identifier of the form `v<N>`. |

### Body fields

| Field | Type | Required | Description |
|------|-----|--------------|----------|
| `tags` | string[] | no | The new full list of tags. **Replaces** the existing tags entirely. If the field is omitted, the tags are left unchanged. |
| `note` | string \| null | no | Note. A string — overwrites the current one. `null` — clears the note. If the field is omitted, the note is left unchanged. |

You can pass only `tags`, only `note`, or both fields at once.

### Response

`HTTP 200`:

```json
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"],
    "note": "Final version before release"
  }
}
```

### Examples

#### curl — add the `manual` tag

```bash
curl -X PATCH https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tags": ["manual"] }'
```

#### curl — clear the note

```bash
curl -X PATCH https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3 \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "note": null }'
```

#### JavaScript

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3`,
  {
    method: 'PATCH',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tags: ['manual'], note: 'Final version' }),
  },
)
```

### Error codes

| HTTP | Code | When returned |
|------|-----|---------------------|
| 400 | `INVALID_METADATA` | The body failed validation (invalid tags or field types). |
| 400 | `INVALID_VERSION_ID` | The `versionId` format does not match `v<non-negative integer>`. |
| 403 | `SOURCE_APP_ID_MISMATCH` | The call was made with an authorization key `vibe_app_…` issued for a different application. Such a key can access only its own application's snapshots, even when both applications were created by the same author. |
| 403 | `NOT_AUTHORIZED` | Only the application author, the application OAuth key, or a Bitrix24 account administrator can manage snapshots. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | The application does not exist, was deleted, or belongs to another portal. |
| 404 | `VERSION_NOT_FOUND` | A version with this `versionId` does not exist or was deleted. |

## Setting and removing a tag

`POST /v1/apps/:id/sources/:versionId/tag`

Two tags are recognized, and both protect the version from automatic cleanup:

- `manual` — the version is pinned manually by an operator.
- `published` — the version is recorded as published (this tag is also set automatically after `POST /v1/apps/:id/publish`).

### Path parameters

| Parameter | Type | Description |
|----------|-----|----------|
| `id` (path) | UUID | Application identifier. |
| `versionId` (path) | string | Version identifier of the form `v<N>`. |

### Body fields

| Field | Type | Required | Description |
|------|-----|--------------|----------|
| `tag` | string | yes | `manual` or `published`. |
| `action` | string | yes | `add` — add the tag, `remove` — remove it. |

### Response

`HTTP 200`:

```json
{
  "success": true,
  "data": {
    "versionId": "v3",
    "tags": ["manual"]
  }
}
```

### Examples

#### curl

```bash
curl -X POST https://vibecode.bitrix24.com/v1/apps/<APP_ID>/sources/v3/tag \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tag": "manual", "action": "add" }'
```

#### JavaScript

```javascript
await fetch(
  `https://vibecode.bitrix24.com/v1/apps/${appId}/sources/v3/tag`,
  {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.VIBE_APP_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ tag: 'manual', action: 'add' }),
  },
)
```

### Error codes

| HTTP | Code | When returned |
|------|-----|---------------------|
| 400 | `INVALID_TAG` | The tag is not one of `manual`, `published`. |
| 400 | `INVALID_ACTION` | The action is neither `add` nor `remove`. |
| 400 | `INVALID_VERSION_ID` | The `versionId` format does not match `v<non-negative integer>`. |
| 403 | `SOURCE_APP_ID_MISMATCH` | The call was made with an authorization key `vibe_app_…` issued for a different application. Such a key can access only its own application's snapshots, even when both applications were created by the same author. |
| 403 | `NOT_AUTHORIZED` | Only the application author, the application OAuth key, or a Bitrix24 account administrator can manage snapshots. |
| 403 | `INFRA_FORBIDDEN_FOR_COWORK_KEY` | The call was made with a Cowork/Code key — such a key works with data only and cannot perform write operations. To issue a key that can, see [Project key for deploy](/docs/cowork/deploy-key). |
| 404 | `APP_NOT_FOUND` | The application does not exist, was deleted, or belongs to another portal. |
| 404 | `VERSION_NOT_FOUND` | A version with this `versionId` does not exist or was deleted. |

The full code reference — [Error codes](/docs/errors).

## See also

- [Source code storage](/docs/source-storage)
- [Version list and download](/docs/source-storage/versions)
- [Deleting versions](/docs/source-storage/delete)
- [Version lifetime and cleanup](/docs/source-storage/retention)
- [Save a snapshot](/docs/source-storage/save)