API reference

Lists

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

GET/api/v1/listsThe workspace's creator lists, most recently updated first; q searches names.

Every agency creator list of the workspace, as every staff member sees them in the app: id, name, description, color, creator_count, share_enabled, created_at, updated_at. Sorted by updated_at (newest first); paged with page/limit (limit ≤ 100, default 50).

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

Input

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/listsCreate a creator list, optionally with roster creators (and their quoted rates, admin + finance:read).

Creates an agency creator list through the canonical helper (createListFromInput — the same validation as the app: a name of 1-120 characters, every creator an ACTIVE roster creator of this workspace or 400). quoted_rates sets an integer-cent quote per selected creator and needs an admin member AND finance:read (403 otherwise). Returns 201 with the list.

Scopes
lists: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.
color bodystring — #rrggbb
creator_ids bodyarray of string (uuid) — Active roster creators to add, in list order.
description bodystring | null
name body, requiredstring
quoted_rates bodyarray of object — Quoted rate (integer cents) per selected creator. Admin members with finance:read only.

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)
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/lists/{list_id}One creator list: name, description, color, member count and its updated_at version.

One agency creator list (members via GET /lists/{id}/members). Unknown, cross-workspace or archived ids return 404.

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

Input

list_id path, requiredstring (uuid) — List 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/lists/{list_id}Rename a list or change its description or color. Send expected_updated_at.

Partial update through the canonical helper (updateListFromInput, the same versioned RPC as the app). expected_updated_at (the updated_at from GET /lists/{id}) is required: missing is 428 expected_updated_at_required, a list changed since is 409 stale_target and nothing is written. A shared list's public page refreshes.

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

Input

list_id path, requiredstring (uuid) — List 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.
color bodystring — #rrggbb
description bodystring | null
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.
name bodystring

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)
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/lists/{list_id}Delete a creator list. Runs directly within the daily delete cap.

Deletes one creator list in this workspace (its members stay on the roster). A `delete`-class action: it deletes at once and answers 200 { status: "deleted" }, within the credential's daily delete cap (429 daily_delete_cap_reached past it). Requires the lists:read and delete scopes, an Idempotency-Key, and an admin or manager member.

Scopes
lists:read + delete
Members
admin, manager
Runs
Directly; delete class
Idempotency-Key
required
Rate weight
1

Input

list_id path, requiredstring (uuid) — List id in this workspace.
expected_updated_at querystring — The list's updated_at as you last read it. Optional: when given, a list 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 / 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/lists/{list_id}/membersThe creators on a list, in list order (quoted rates for admin keys with finance:read).

Members of one list in their manual order: creator_id, position, added_at and creator {id, display_name, primary_platform, total_reach, former_at}. quoted_rate_cents (integer cents) is included only for an admin member's key that holds finance:read. Paged with page/limit (limit ≤ 100, default 50).

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

Input

list_id path, requiredstring (uuid) — List id in this workspace.
limit queryinteger — Page size, default 50.
page queryinteger — 1-based page, default 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/lists/{list_id}/membersAdd and/or remove roster creators on a list in one atomic change.

One atomic membership change through the canonical helper (changeListMembers — the same RPC as the app and Atlas): add_creator_ids must be ACTIVE roster creators of this workspace (400 otherwise), a creator cannot be both added and removed, adding an existing member is a no-op. Returns the counts and the list's new updated_at.

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

Input

list_id path, requiredstring (uuid) — List 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.
add_creator_ids bodyarray of string (uuid)
remove_creator_ids bodyarray 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)
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
PATCH/api/v1/lists/{list_id}/orderSet the manual order of a list's members (every member, exactly once). Send expected_updated_at.

Reorders through the canonical helper (reorderListMembers, the same RPC as the app's drag-and-drop): creator_ids must be exactly the list's current members. expected_updated_at is required (428 when missing); a list changed since is 409 stale_target; a membership mismatch is 409 conflict.

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

Input

list_id path, requiredstring (uuid) — List 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.
creator_ids body, requiredarray of string (uuid)
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.

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)
409stale_target / conflict / 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
POST/api/v1/lists/{list_id}/duplicateCopy a list with its members, order and quoted rates into a new list.

Duplicates through the canonical helper (duplicateListFromId, as the app's Duplicate): members, their order and their quoted rates are copied; name defaults to "<name> copy". Returns 201 with the new list.

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

Input

list_id path, requiredstring (uuid) — List 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.
color bodystring — #rrggbb
description bodystring | null
name bodystring

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)
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
PATCH/api/v1/lists/{list_id}/members/{creator_id}Set or clear one list member's quoted rate (integer cents). Admin members with finance:read.

Sets one member's quoted rate on a list (integer cents, 0-100,000,000; null clears it) through the canonical helper (the app's rate cell write). Quoted rates are agency financial data: the key needs lists:write AND finance:read and an admin member. A creator who is not on the list is 404.

Scopes
lists:write + finance:read
Members
admin
Idempotency-Key
optional
Rate weight
1

Input

list_id path, requiredstring (uuid) — List id in this workspace.
creator_id path, requiredstring (uuid) — A creator on this list.
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.
quoted_rate_cents body, requiredinteger | null

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)
500internal_error / idempotent_replay_of_failure
503service_unavailable
POST/api/v1/lists/{list_id}/shareTurn on a list's public share link (what it shows is the list's share settings in TLNT). Runs directly (one of the credential's public links per day).

Publishes the list's public page with the list's stored share settings (which fields show, live or frozen snapshot — configured on the list's Share page in TLNT; the API cannot change them). 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. An archived or another workspace's list is 404.

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

Input

list_id path, requiredstring (uuid) — List 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.
expected_updated_at bodystring — Optional: the updated_at you last read. A record changed since is refused (409 stale_target).

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 / idempotency_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/lists/{list_id}/shareTurn off a list's public share link; the public page stops working from the next request.

Revokes the list's public link through the same path as the app (share_enabled off, the public render cache refreshed): the public page and its token / slug URLs 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
lists:read + share:public
Members
admin, manager
Idempotency-Key
optional
Rate weight
1

Input

list_id path, requiredstring (uuid) — List 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