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:

{
  "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.

2.7 KiB Raw Blame History