# Collaborators API

Base path: `/api/v1/collaborators`

All endpoints require `Authorization: Bearer <jwt>`.

Related: [[02 - Description Engine]], [[03 - Blocks API]], [[04 - Database Schema]]

---

## GET /collaborators

List all collaborators for the current team.

**Response:** `Collaborator[]`

---

## GET /collaborators/:id

Get a single collaborator by ID.

**Response:** `Collaborator`

---

## POST /collaborators

Create a new collaborator. Requires `EDITOR` role.

**Request body:**

```json
{
  "name": "string",
  "youtubeLink": "https://www.youtube.com/@handle",
  "twitchLink": "https://www.twitch.tv/handle",
  "instagramLink": "https://www.instagram.com/handle",
  "tiktokLink": "https://www.tiktok.com/@handle",
  "twitterLink": "https://x.com/handle",
  "blueskyLink": "https://bsky.app/profile/handle",
  "discordHandle": "username",
  "aliases": ["string"],
  "notes": "string"
}
```

All platform link fields are optional. `discordHandle` stores a username string rather than a URL.

---

## PATCH /collaborators/:id

Update a collaborator. Requires `EDITOR` role.

**Request body:** Same fields as `POST /collaborators`, all optional.

---

## DELETE /collaborators/:id

Delete a collaborator. Requires `ADMIN` role.

> Before deleting, check whether the collaborator is still referenced in any `Video.collaboratorIds` JSON array. Use the `array_contains` Prisma operator to query this field.

---

## Collaborator tokens in descriptions

When a `COLLABORATOR` or `VARIABLE` block references a collaborator, the following `{collab.*}` tokens are available:

| Token | Resolves to |
|---|---|
| `{collab.name}` | Collaborator's display name |
| `{collab.youtube}` | Full YouTube URL (e.g. `https://www.youtube.com/@handle`) |
| `{collab.twitch}` | Twitch link |
| `{collab.instagram}` | Instagram link |
| `{collab.tiktok}` | TikTok link |
| `{collab.twitter}` | Twitter/X link |
| `{collab.bluesky}` | Bluesky link |
| `{collab.discord}` | Discord handle |
| `{collab.aliases}` | Aliases list |
| `{collab.notes}` | Notes field |

> The legacy `{collab.handle}` token is no longer supported. Any block content still using it will not resolve — update those blocks manually to `{collab.youtube}`.

All tokens are registered in `shared/system-variables/system-variables.registry.ts`. See [[02 - Description Engine]] for how they are resolved.

---

## Collaborator tracking

Collaborators are assigned to a video via `Video.collaboratorIds` — a JSON string array of collaborator IDs stored directly on the `Video` row. This is the single source for both rendering (`{collab.*}` token resolution) and filtering (the `collaboratorId` query param on `GET /videos`). There is no separate join table.