# Launch tags

> Create colored tags and attach them to launches.

Tags group launches in your dashboard. Each tag has a name and a color, and a launch can carry several. Your tags and each launch's `tag_ids` are listed with your launches.

Base URL: `https://api-mig.proxima.tools`

## Endpoints

- `POST /launch/tags/create-tag`: Create a tag
- `POST /launch/tags/update-tag`: Update a tag
- `POST /launch/tags/delete-tag`: Delete a tag
- `POST /launch/tags/tag-launches`: Tag launches
- `POST /launch/tags/untag-launches`: Untag launches

### Create a tag

`POST /launch/tags/create-tag`

Creates a launch tag. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Check before retrying. Each call creates a new tag, even with the same name. Look for it in `tags` from [List the license's launches](/reference/licenses/#list-mints) before sending it again.

> Not called by the current web app.

#### Body parameters

- `name` (string, required): Tag name, up to 25 characters.
- `color` (string, required): Color as `#RRGGBB`.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `message` (string): Human-readable outcome.
- `tag_id` (integer): ID of the new tag.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Tag name too long` | `name` is longer than 25 characters. | Shorten `name` to 25 characters or fewer. |
| 400 | `bad_request` | `color must be a hex string like #RRGGBB` | `color` is not `#` followed by six hex digits. | Send `color` as `#RRGGBB`, for example `#7C5CFF`. |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/tags/create-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Week 44",
  "color": "#7C5CFF"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully created tag",
  "tag_id": 42
}
```

### Update a tag

`POST /launch/tags/update-tag`

Renames and recolors a launch tag. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat sets the same name and color again.

> Not called by the current web app.

#### Body parameters

- `tag_id` (string, required): Tag ID, as a string.
- `new_name` (string, required): New name, up to 25 characters.
- `new_color` (string, required): New color as `#RRGGBB`.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `message` (string): Human-readable outcome.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `Tag name too long` | `new_name` is longer than 25 characters. | Shorten `new_name` to 25 characters or fewer. |
| 400 | `bad_request` | `color must be a hex string like #RRGGBB` | `new_color` is not `#` followed by six hex digits. | Send `new_color` as `#RRGGBB`, for example `#22C55E`. |
| 404 | `not_found` | `Tag not found` | No tag with this `tag_id` belongs to your license. | Use a tag `id` from `tags` in [List the license's launches](/reference/licenses/#list-mints). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/tags/update-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": "42",
  "new_name": "Week 44 winners",
  "new_color": "#22C55E"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully updated tag"
}
```

### Delete a tag

`POST /launch/tags/delete-tag`

Deletes a launch tag. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat after a successful delete answers `404` with `Tag not found`.

> Not called by the current web app.

#### Body parameters

- `tag_id` (string, required): Tag ID, as a string.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `message` (string): Human-readable outcome.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 404 | `not_found` | `Tag not found` | No tag with this `tag_id` belongs to your license, or it is already deleted. | Use a tag `id` from `tags` in [List the license's launches](/reference/licenses/#list-mints). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/tags/delete-tag" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": "42"
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully deleted tag"
}
```

### Tag launches

`POST /launch/tags/tag-launches`

Attaches a tag to one or more launches. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. Launches that already carry the tag are skipped, so a repeat answers `linked: 0`.

> Not called by the current web app.

#### Body parameters

- `tag_id` (string, required): Tag ID, as a string.
- `launch_ids` (array<string>, required): Public IDs of the launches, as strings.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `message` (string): Human-readable outcome.
- `linked` (integer): Launches newly tagged. Launches that already carry the tag and IDs that do not belong to your license are skipped without an error.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `No launch ids provided` | `launch_ids` is empty. | Send at least one launch ID in `launch_ids`. |
| 404 | `not_found` | `Tag not found` | No tag with this `tag_id` belongs to your license. | Use a tag `id` from `tags` in [List the license's launches](/reference/licenses/#list-mints). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/tags/tag-launches" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": "42",
  "launch_ids": [
    "101482937561204",
    "101907315264588"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully tagged launches",
  "linked": 2
}
```

### Untag launches

`POST /launch/tags/untag-launches`

Removes a tag from one or more launches. (Bearer JWT)

- Token: Upgraded session token, bound to a license.
- Read-only tokens: refused with `403 read_only_token`.
- Retry: Safe to retry. A repeat finds nothing left to remove and answers `removed: 0`.

> Not called by the current web app.

#### Body parameters

- `tag_id` (string, required): Tag ID, as a string.
- `launch_ids` (array<string>, required): Public IDs of the launches, as strings.

#### Returns 200 OK

- `ok` (boolean): `true` when the request succeeded.
- `message` (string): Human-readable outcome.
- `removed` (integer): Launches the tag was removed from. Launches without the tag and IDs that do not belong to your license are skipped without an error.

#### Errors

| Status | Code | Message | When | What to do |
| --- | --- | --- | --- | --- |
| 400 | `bad_request` | `No launch ids provided` | `launch_ids` is empty. | Send at least one launch ID in `launch_ids`. |
| 404 | `not_found` | `Tag not found` | No tag with this `tag_id` belongs to your license. | Use a tag `id` from `tags` in [List the license's launches](/reference/licenses/#list-mints). |

#### Example request

```bash
curl -X POST "https://api-mig.proxima.tools/launch/tags/untag-launches" \
  -H "Authorization: Bearer $PROXIMA_JWT" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_id": "42",
  "launch_ids": [
    "101907315264588"
  ]
}'
```

#### Example response

```json
{
  "ok": true,
  "message": "Successfully untagged launches",
  "removed": 1
}
```
