94 lines
2.7 KiB
Markdown
94 lines
2.7 KiB
Markdown
# 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.
|