API reference

Roster

12 operations. REST https://dev.tlntconnect.com/api/v1

GET/api/v1/rosterList roster creators: names, platform handles, reach, status. Active roster by default; include_former=true adds off-roster creators.

The workspace roster, as every staff member sees it in the app. Rows carry id, display_name, primary_platform, tiktok_username, ig_username, youtube_channel_id, x_username, total_reach, status, niche, primary_niche, former_at, created_at. Sorted by name; paged with page/limit (limit ≤ 100, default 50).

Scopes
roster:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Input

include_former queryboolean — true adds off-roster (former) creators.
limit queryinteger — Page size, default 50.
page queryinteger — 1-based page, default 1.
q querystring — Name search.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/rosterAdd a creator to the roster. display_name is required; a matching email/handle already on the roster returns duplicate_creator with the existing id.

Adds a creator through the canonical roster create path (src/lib/roster/mutations.ts): allowlisted, normalised fields (handles stored lowercase; YouTube channel ids (UC…) keep their case); 409 duplicate_creator (with existing_id) on a matching email or handle (Instagram, TikTok and X handles and YouTube @handles match in any case; YouTube channel ids (UC…) match exact case only); the trial roster cap (402 trial_limit_reached, exactly the refusal the app gives); billable-seat sync. The creator is assigned to the key's member. Returns 201 with id, display_name, status, created_at.

Scopes
roster:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
email bodystring | null
ig_username bodystring | null
location bodystring | null
niche bodyarray of string | string | null — Niches as an array of strings or one comma-separated string.
primary_niche bodystring | null
primary_platform bodystring | null
status body"discovered" | "qualified" | "queued" | "contacted" | "replied" | "signed_up" | "onboarded" | "activated" | "monetizing"
tiktok_username bodystring | null
total_reach bodynumber | null
x_username bodystring | null
youtube_channel_id bodystring | null
display_name body, requiredstring

Responses

201Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
402trial_limit_reached
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409duplicate_creator / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/roster/{creator_id}One roster creator by id: handles, reach, status, niches, location, ownership and bio.

Roster creator detail: the list columns plus location, ownership_status, bio and updated_at (pass updated_at back as expected_updated_at to update the creator). The bio is the creator's own text and is labelled untrusted. Unknown or cross-workspace ids return 404.

Scopes
roster:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1
Untrusted fields
bio

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
PATCH/api/v1/roster/{creator_id}Update a roster creator's allowlisted fields (handles, status, niche, reach; ownership, and restoring a former creator, for admins). Send expected_updated_at.

Partial update through the canonical roster write (src/lib/roster/mutations.ts — the same activity log, notifications and seat sync as the app), with the same field allowlist as create (nothing required). Pass null to clear a clearable field; present-but-invalid values are a 400, never a silent null. expected_updated_at (the updated_at from GET /roster/{id}) is required: missing is 428 expected_updated_at_required, a creator changed since is 409 stale_target and nothing is written. ownership_status (exclusive | non_exclusive | null) and former: false (restores a former creator to the active roster) move billable seats, so they need roster:write AND an admin member (403 role_forbidden otherwise) and sync the subscription's seat count; restoring a former creator past a trial's roster allowance is 402 trial_limit_reached. former: true is refused (400 invalid_input): archiving is archive_roster_creator (DELETE /roster/{id}), which needs the delete scope and runs directly within the daily delete cap. Cross-workspace ids return 404.

Scopes
roster:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
email bodystring | null
ig_username bodystring | null
location bodystring | null
niche bodyarray of string | string | null — Niches as an array of strings or one comma-separated string.
primary_niche bodystring | null
primary_platform bodystring | null
status body"discovered" | "qualified" | "queued" | "contacted" | "replied" | "signed_up" | "onboarded" | "activated" | "monetizing"
tiktok_username bodystring | null
total_reach bodynumber | null
x_username bodystring | null
youtube_channel_id bodystring | null
display_name bodystring
expected_updated_at bodystring — The record's updated_at as you last read it (ISO 8601). Required on updates: a missing one is 428 expected_updated_at_required, an older one 409 stale_target.
former bodyfalse — false restores a former creator to the active roster. Admin members only. To archive, use archive_roster_creator.
ownership_status body"exclusive" | "non_exclusive" | null — exclusive | non_exclusive, or null to un-roster. Admin members only.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
402trial_limit_reached
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409stale_target / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
428expected_updated_at_required
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
DELETE/api/v1/roster/{creator_id}Move a creator off the active roster (former). Runs directly within the daily delete cap.

Archives one roster creator — the reversible "former" soft delete the app's roster remove uses (delete_creators(): nothing is destroyed, campaigns, deliverables and payments stay). A `delete`-class action on an admin member's key with roster:write and delete: it archives at once (200 { status: "archived" }) within the credential's daily delete cap, and syncs billable seats. An already-former creator is 409 conflict; with expected_updated_at, a creator changed since is 409 stale_target. Restore with PATCH /roster/{id} { former: false }.

Scopes
roster:write + delete
Members
admin
Runs
Directly; delete class
Idempotency-Key
required
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
expected_updated_at querystring — The record's updated_at as you last read it. Optional: when given, a record changed since then is refused (409 stale_target). In a query string, URL-encode it (+ as %2B).
Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409stale_target / conflict / idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_delete_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/roster/{creator_id}/notesThe team's internal notes on one roster creator, pinned first, newest first.

Internal notes on a roster creator, as every staff member sees them on the creator profile: id, content, is_pinned, author_id, created_at, updated_at; pinned first, then newest. At most 100. Cross-workspace ids return 404.

Scopes
roster:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
POST/api/v1/roster/{creator_id}/notesAdd an internal note to a roster creator (notifies the creator's assignee).

Adds an internal note through the canonical note service (the same RPC and assignee notification as the app). Managers add notes only on creators assigned to them (403 otherwise), as in the app. content: 1-10,000 characters. Returns 201 with the note.

Scopes
roster:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
content body, requiredstring

Responses

201Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member) / creator_not_found
409idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
GET/api/v1/tagsThe workspace's creator tags (id, name, color), for set_roster_creator_tags.

The workspace's creator tags, sorted by name: id, name, color. Use the ids with PATCH /roster/{id}/tags.

Scopes
roster:read
Members
admin, manager, scout, viewer
Idempotency-Key
Ignored (read)
Rate weight
1

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
429rate_limited (honour Retry-After)
500internal_error
PATCH/api/v1/roster/{creator_id}/tagsReplace a roster creator's tags with exactly the given tag ids (an empty list clears them).

Replaces the creator's tags through the canonical tag service (one atomic RPC). tag_ids are workspace tags from GET /tags (up to 100); an unknown or cross-workspace tag is 400. Managers tag only creators assigned to them (403 otherwise), as in the app.

Scopes
roster:write
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.
tag_ids body, requiredarray of string (uuid)

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member) / creator_not_found
409idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After)
500internal_error / idempotent_replay_of_failure
503service_unavailable
POST/api/v1/roster/{creator_id}/media-kit/sharePublish (or copy the live link of) a roster creator's media kit. Runs directly (one of the credential's public links per day).

Publishes the creator's live media kit with its media kit settings (sections, metrics, contact — configured in TLNT). An already-live kit keeps its link (no new token). A `public_share`-class action under share:public: it runs at once and answers 200 { status: "shared", data: { share_url } }, counting one of the credential's public links per day (default 25, up to 200; 429 daily_public_link_cap_reached past it).share_url. Requires an Idempotency-Key. A former (archived) or another workspace's creator is 404.

Scopes
roster:read + share:public
Members
admin, manager
Runs
Directly; public_share class
Idempotency-Key
required
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
Idempotency-Key header, requiredstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.

Responses

200Success
202pending_approval — a retry with the same Idempotency-Key found this request's action still open (still running, or queued before in-app approval was removed); poll it
400invalid_input / invalid_json / invalid_id / idempotency_key_required
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_public_link_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable
DELETE/api/v1/roster/{creator_id}/media-kit/shareUnpublish a creator's media kit; its public page stops working from the next request.

Unpublishes the kit through the same path as the app (media_kit_share_enabled off): the public page and its image proxy 404 from the next request. Runs directly (it only narrows exposure) under share:public and counts against the key's daily delete cap (429 daily_delete_cap_reached past it); idempotent.

Scopes
roster:read + share:public
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

creator_id path, requiredstring (uuid) — Roster creator id in this workspace.
Idempotency-Key headerstring — Retry-safe key (1-255 printable ASCII; a UUID is recommended; an RFC 8941 quoted string is accepted). The same key with the same request within 24h replays the stored response byte for byte (Idempotent-Replayed: true) without running again; the replay still consumes the operation's rate weight.

Responses

200Success
400invalid_input / invalid_json / invalid_id
401missing_token / invalid_token / revoked_token / expired_token
403missing_scope / actor_unavailable / plan_upgrade_required / role_forbidden
404not_found (unknown, cross-workspace or not visible to the key's member)
409idempotency_key_reused / idempotency_in_progress / idempotency_context_changed / idempotency_response_too_large
429rate_limited (honour Retry-After) / daily_delete_cap_reached
500internal_error / idempotent_replay_of_failure
503service_unavailable