Campaigns
32 operations. Each REST operation is also an MCP tool of the same name. REST https://tlntconnect.com/api/v1
GET/api/v1/campaigns
Campaigns visible to the key's member (admins: all; managers: owned, assigned or creator-linked campaigns; others: campaigns they collaborate on). Rows carry id, name, status, deal_status, deal_type, deal_value_cents (admin members on keys with finance:read only), start_date, end_date, created_at, updated_at and brand {id, name}. Paged with page/limit (limit ≤ 100, default 50).
list_campaignscampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
deal_status query"pitching" | "negotiating" | "contract_sent" | "in_progress" | "paid" | "completed" | "lost"deal_type query"one_time" | "multi_round"limit queryinteger — Page size, default 50.page queryinteger — 1-based page, default 1.q querystring — Name search.Responses
POST/api/v1/campaigns
Create a deal through the same canonical helper as the app (validation, cross-tenant brand/creator checks, campaign_creators/campaign_managers bookkeeping, live-campaign plan limits). deal_value is DOLLARS on input. deal_value and agency_fee_pct need an admin member AND a key with finance:read; otherwise the request is refused with 403 (role_forbidden for a non-admin member, missing_scope for a key without finance:read) naming the field (nothing is written). Returns 201 with the campaign row (financial fields only for admin members on keys with finance:read).
create_campaigncampaigns:write- admin, manager
- optional
- 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.agency_fee_pct bodynumber — Agency fee percentage (0-100). Needs an admin member and a key with the finance:read scope (403 role_forbidden / missing_scope otherwise).brand_id bodystring (uuid) | null — Brand in this workspace to attach the deal to. Admin members only on update.color bodystring | null — #rrggbbdeal_status body"pitching" | "negotiating" | "contract_sent" | "in_progress" | "paid" | "completed" | "lost"deal_type body"one_time" | "multi_round"deal_value bodynumber — Deal value in DOLLARS (stored as cents). Needs an admin member and a key with the finance:read scope (403 role_forbidden / missing_scope otherwise).end_date bodystring | nullname body, requiredstringnotes bodystring | nullpayment_terms bodystring | nullstart_date bodystring | nullusage_rights bodystring | nullcreator_ids body, requiredarray of string (uuid) — Roster creator ids in this workspace.duration_months bodyinteger — Multi-round deals only.Responses
GET/api/v1/campaigns/{campaign_id}
Campaign detail plus creators (id, status, rate_cents, creator {id, display_name, primary_platform}) and deliverables (id, status, draft_due, post_due). Unknown, cross-workspace or not-visible ids return 404. A manager who does not own the campaign sees only the rows of creators assigned to them, as in the app. deal_value_cents and per-creator rate_cents need an active admin member who is not only a collaborator, on a key with finance:read.
get_campaigncampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.Responses
PATCH/api/v1/campaigns/{campaign_id}
Partial update through the canonical campaign helper: allowlisted fields, enum and date-order validation, field gating (brand_id, manager_id, contract/invoice status need an admin member; deal_value and agency_fee_pct need an admin member AND a key with finance:read — 403 role_forbidden / missing_scope naming the field otherwise) and deal-outcome stamping credited to the key's member. Managers can only update campaigns they can see; others read as 404. brand_id / manager_id must reference this workspace (404 brand_not_found / manager_not_found).
update_campaigncampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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.agency_fee_pct bodynumber — Agency fee percentage (0-100). Needs an admin member and a key with the finance:read scope (403 role_forbidden / missing_scope otherwise).brand_id bodystring (uuid) | null — Brand in this workspace to attach the deal to. Admin members only on update.color bodystring | null — #rrggbbdeal_status body"pitching" | "negotiating" | "contract_sent" | "in_progress" | "paid" | "completed" | "lost"deal_type body"one_time" | "multi_round"deal_value bodynumber — Deal value in DOLLARS (stored as cents). Needs an admin member and a key with the finance:read scope (403 role_forbidden / missing_scope otherwise).end_date bodystring | nullname bodystringnotes bodystring | nullpayment_terms bodystring | nullstart_date bodystring | nullusage_rights bodystring | nullcontract_status body"none" | "sent" | "signed" | "expired"invoice_status body"none" | "sent" | "paid" | "overdue"manager_id bodystring (uuid) | null — Team member in this workspace. Admin members only.outcome_reason bodystring | null — Only on closed deals (paid, completed, lost).status body"draft" | "active" | "paused" | "completed" | "cancelled"Responses
DELETE/api/v1/campaigns/{campaign_id}
Deletes one campaign/deal exactly as the app's Delete deal does: in one transaction its invoices, payouts, files, casting calls and email threads are UNLINKED (they survive), its creators, deliverables and managers go with it, and its open Home cards are resolved. A Brand deal with money, a signature or history keeps the whole campaign (409 conflict). A `delete`-class action: by default it deletes at once and answers 200 { status: "deleted" }, within the credential's daily delete cap (429 daily_delete_cap_reached past it). When the credential asks for approval in TLNT for deletes, the call answers 202 { status: "pending_approval", action_id, approval_url } instead and a workspace admin approves or rejects it in TLNT; poll GET /actions/{action_id}. The approver signs off on the campaign as it was when you asked: one edited before approval is not deleted (the action reports failed). Optional expected_updated_at: a campaign changed since you read it is 409 stale_target. Requires the campaigns:read and delete scopes, an Idempotency-Key, and an admin member (as in the app).
delete_campaigncampaigns:read+delete- admin
- Runs directly; queued when the credential asks for approval for delete
- required
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.expected_updated_at querystring — The campaign's updated_at as you last read it. Optional: when given, a campaign 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
POST/api/v1/campaigns/{campaign_id}/creators
Attach roster creators to a deal through the canonical platform-mutation RPC, which re-verifies the acting member, checks every creator belongs to this workspace and applies manager scope. Body: creator_ids (1-100), optional status, rate (DOLLARS — needs an admin member and a key with finance:read, 403 role_forbidden / missing_scope naming it otherwise) and notes.
add_campaign_creatorscampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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)notes bodystring | nullrate bodynumber — Per-creator rate in DOLLARS (stored as cents). Needs an admin member and a key with the finance:read scope (403 role_forbidden / missing_scope otherwise).status body"invited" | "confirmed" | "declined" | "completed"Responses
POST/api/v1/campaigns/{campaign_id}/duplicate
Copies a campaign the key's member can see through the app's own duplicate helper: a new draft (deal_status pitching) owned by the key's member, with the source's brand, deal type, dates, payment terms, usage rights and creators (as invited). The deal value and agency fee are copied only for an admin member on a key with finance:read; otherwise the copy starts at 0. Optional name (default "<name> (copy)"), notes and color override the source. Returns 201 with the new campaign row. A source the member cannot see is 404.
duplicate_campaigncampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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 | null — #rrggbb; null clears it.name bodystringnotes bodystring | nullResponses
POST/api/v1/campaigns/import
Bulk-imports an agency's existing deal book through the app's own importer (POST /api/campaigns/import): each valid row becomes a campaign, a link to an EXISTING roster creator (matched by name, handle, profile URL or email — never created) and its catalog deliverables, written in transactional chunks. Brands are matched by name or created. Per-row problems are reported, not fatal: the answer is { imported, failed, total, errors (first 25), errors_truncated, warnings }. Admin members only (deals carry money); deal_value, rate and agency_fee_pct also need a key with finance:read (403 missing_scope naming deals.<n>.<field> otherwise). Requires an Idempotency-Key: a retried import never creates the deals twice.
import_campaignscampaigns:write- admin
- required
- 5
Input
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.deals body, requiredarray of objectResponses
GET/api/v1/campaigns/{campaign_id}/report
The same client-safe payload as the shared campaign report page (built by the same code, TLN-919): campaign {id, name, status, start_date, end_date, usage_rights}, brand {name, logo_url, website}, report {status live|final (null before any post is tracked), as_of, settings}, totals {views, engagements, engagement_rate, likes, comments, shares, saves, posts_live, posts_total}, views_over_time [{date, views}], posts (id, creator {id, display_name, handle} or null, platform, format, posted_at, post_url, thumbnail_url, live, from_deliverable, views, likes, comments, shares, saves, engagements, engagement_rate), creators (id, status, creator {id, display_name, handle, primary_platform}, posts, views, engagements, engagement_rate), deliverables (an empty array unless the agency shows the checklist; then type, status, quantity, post_due, posted_at, content_url, creator) and stats {total_deliverables, completed_deliverables, completion_rate, total_creators, finance_visible: false}. It honours the report's 'what the brand sees' settings exactly as the shared page does: a metric the agency hid is null. Each metric is the post's latest reported value inside this campaign's tracking window; engagement rate = (likes + comments + shares) / views as a fraction; an unreported metric is null, as are engagements and rate when the like count is hidden. Money, link clicks, reach and impressions are never included, whatever the key's scopes. A manager who does not own the campaign sees only their assigned creators' rows and posts. A campaign the member cannot see is 404. content_url and post_url are creator-submitted and labelled untrusted.
get_campaign_reportcampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
content_urlpost_url
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.Responses
PATCH/api/v1/campaigns/{campaign_id}/creators/{creator_id}
Updates one campaign creator (the deal row) through the app's own per-creator update: status (invited, confirmed, declined, completed), notes, and rate (DOLLARS, stored as integer cents). Admin members only, as in the app; rate also needs a key with finance:read (403 missing_scope naming rate otherwise). A Brand V5 deal whose status follows its deal state, or whose sent offer locks its rate, answers 409 conflict. A campaign or creator outside this workspace, or a creator not on the campaign, is 404. The answer is the updated row (rate_cents only on keys with finance:read).
update_campaign_creatorcampaigns:write- admin
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.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.notes bodystring | nullrate bodynumber — Rate in DOLLARS (stored as cents). Needs a key with finance:read.status body"invited" | "confirmed" | "declined" | "completed"Responses
DELETE/api/v1/campaigns/{campaign_id}/creators/{creator_id}
Removes one creator from a campaign through the app's own per-creator delete: the deal row goes, the creator stays on the roster. Admin members only, as in the app. A Brand V5 deal with money, a signature or history — or one a payment, hold or other record still references — is kept (409 conflict). A campaign or creator outside this workspace, or a creator not on the campaign, is 404.
remove_campaign_creatorcampaigns:write- admin
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.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
GET/api/v1/campaigns/{campaign_id}/creators/{creator_id}/rate-suggestion
The app's rate suggestion: the creator's own rate-card price for each deliverable they are assigned on this campaign, times its quantity, summed (suggested_cents), plus the lines and how many deliverables have no rate-card price (missing_count). Read-only. Money: admin members only, on a key with finance:read. A campaign or creator outside this workspace, or a creator not on the campaign, is 404.
get_creator_rate_suggestioncampaigns:read+finance:read- admin
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.creator_id path, requiredstring (uuid) — Roster creator id in this workspace.Responses
GET/api/v1/campaigns/{campaign_id}/collaborators
The campaign team panel: current collaborators (read-only teammates invited onto this campaign, with who invited them and when), and — for a member who can manage the campaign — the active teammates eligible to invite (not admins, who see everything already, and not the campaign's managers). Anyone who can see the campaign may read it; a campaign the member cannot see is 404.
list_campaign_collaboratorscampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.Responses
POST/api/v1/campaigns/{campaign_id}/collaborators
Invites 1-100 teammates as read-only collaborators, through the app's own panel logic. Each must be an active member of this workspace who is not the key's member, not an admin and not one of the campaign's managers (400 invalid_input otherwise; nothing is written). Re-inviting a current collaborator changes nothing. Admins and the managers who can see the campaign may invite; a read-only collaborator gets 403 role_forbidden; a campaign the member cannot see is 404. Answers 201 with the updated team.
add_campaign_collaboratorscampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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.member_ids body, requiredarray of string (uuid) — Team member ids in this workspace.Responses
DELETE/api/v1/campaigns/{campaign_id}/collaborators/{member_id}
Removes one read-only collaborator from the campaign (removing a teammate who is not a collaborator changes nothing; a member id outside this workspace is 404). Admins and the managers who can see the campaign may remove; a campaign the member cannot see is 404. Answers with the updated team.
remove_campaign_collaboratorcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.member_id path, requiredstring (uuid) — Team member id of the collaborator.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
GET/api/v1/deal-categories
The workspace's deal-category catalog, by sort order then label (seeded with the defaults the first time it is read, as in the app). active_only=true hides removed categories.
list_deal_categoriescampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
active_only queryboolean — true: active categories only.Responses
POST/api/v1/deal-categories
Adds a category at the end of the catalog (admins and managers, as in the app). The label is trimmed and collapsed (up to 80 characters); one that already exists is 409 conflict. Answers 201 with the category.
create_deal_categorycampaigns:write- admin, manager
- optional
- 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.label body, requiredstringResponses
GET/api/v1/campaigns/{campaign_id}/tracked-posts
The posts tracked for a campaign the key's member can see (404 otherwise), newest first: cadence (standard = daily, hourly), the tracking window, last capture, stopped/gone state, the post (platform, post_url, caption, thumbnail_url, posted_at) and its metric captures (likes, comments, views, shares, saves over time). caption and post_url are authored outside the agency and labelled untrusted. calls_spent is the provider spend so far (calls, not money).
list_campaign_tracked_postscampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
captionpost_url
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.Responses
POST/api/v1/campaigns/{campaign_id}/tracked-posts
Starts tracking one post URL (Instagram, TikTok or YouTube) on a campaign for the app's standard window, through the app's own path: one provider lookup reads the post, its cover is stored durably, and the post is captured daily (cadence standard) or hourly (cadence hourly — a paid plan feature, 403 feature_not_available without it). Each campaign tracks at most the app's maximum of posts at a time (409 conflict past it; stop one first). An unreadable or unsupported URL is 400 invalid_input; a provider outage is 503 service_unavailable (retry later). Adding a post the campaign already tracks restarts it. Weighs 5 rate slots. Admins and the managers who can see the campaign; 404 for a campaign the member cannot see. Answers 201.
track_campaign_postcampaigns:write- admin, manager
- optional
- 5
Input
campaign_id path, requiredstring (uuid) — Campaign 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.cadence body"standard" | "hourly" — standard (daily, default) or hourly (paid plan feature).url body, requiredstring — The post's public URL.Responses
PATCH/api/v1/campaigns/{campaign_id}/tracked-posts/{tracked_post_id}
action "stop" pauses capture (the row and its history stay); "resume" restarts it, extending the tracking window from now if it already ended. A post the platform has removed cannot resume (409 conflict) — remove it and re-add it if the creator restores it. Admins and the managers who can see the campaign; a campaign or tracked post outside the member's view is 404.
update_campaign_tracked_postcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.tracked_post_id path, requiredstring (uuid) — Tracked post id (from list_campaign_tracked_posts).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.action body, required"stop" | "resume"Responses
DELETE/api/v1/campaigns/{campaign_id}/tracked-posts/{tracked_post_id}
Removes one post from the campaign's tracking list. Its captured metrics are not lost: they belong to the post, and tracking it again picks the history back up (which is why a mistyped URL is simply removed). Admins and the managers who can see the campaign; a campaign or tracked post outside the member's view is 404.
remove_campaign_tracked_postcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.tracked_post_id path, requiredstring (uuid) — Tracked post id (from list_campaign_tracked_posts).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
GET/api/v1/campaigns/{campaign_id}/tracking-keywords
The words and @mentions tracked for a campaign the key's member can see (404 otherwise), oldest first, each with how many stored posts matched it so far.
list_campaign_tracking_keywordscampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.Responses
POST/api/v1/campaigns/{campaign_id}/tracking-keywords
Tracks one whole word or @mention (not substrings or punctuation — 400 invalid_input otherwise) on a LIVE campaign (deal_status in_progress; 409 conflict otherwise), then matches it against the posts already stored. Re-adding a tracked keyword returns it unchanged. Admins and the managers who can see the campaign; 404 for a campaign the member cannot see. Answers 201.
add_campaign_tracking_keywordcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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.keyword body, requiredstring — A word or an @mention.Responses
DELETE/api/v1/campaigns/{campaign_id}/tracking-keywords/{keyword_id}
Stops tracking one keyword (its stored matches go with it). Admins and the managers who can see the campaign; a campaign or keyword outside the member's view is 404.
remove_campaign_tracking_keywordcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.keyword_id path, requiredstring (uuid) — Keyword id (from list_campaign_tracking_keywords).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
GET/api/v1/campaigns/{campaign_id}/email-threads
The campaign's links to inbox threads (thread id, mailbox id, status, notes, who linked it and when) — never the emails themselves. Active links by default; status=archived or include_archived=true widen it. Needs the connected-inbox plan features (403 feature_not_available) and, as in the app, an admin or a manager who can see the campaign (collaborators do not see campaign inbox links; 404 otherwise).
list_campaign_email_thread_linkscampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.include_archived querybooleanstatus query"active" | "archived"Responses
POST/api/v1/campaigns/{campaign_id}/email-threads
Links one inbox thread to the campaign, as the app's "Link to deal" does. The key's member must be able to see the campaign (an admin or a manager who can see it; 404 otherwise) and the thread's mailbox (403 role_forbidden otherwise); a thread outside this workspace is 404. A thread already linked to a deal is 409 conflict. Needs the connected-inbox plan features. Answers 201 with the link.
link_campaign_email_threadcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign 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.notes bodystring | nullthread_id body, requiredstring (uuid) — Inbox thread id in this workspace.Responses
DELETE/api/v1/campaigns/{campaign_id}/email-threads/{link_id}
Archives one of the campaign's thread links (archiving twice is a no-op). The inbox thread itself is never deleted. Same access as linking: the campaign (404) and the thread's mailbox (403 role_forbidden); a link outside this campaign is 404. Needs the connected-inbox plan features.
archive_campaign_email_thread_linkcampaigns:write- admin, manager
- optional
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.link_id path, requiredstring (uuid) — Link id (from list_campaign_email_thread_links).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
GET/api/v1/campaigns/{campaign_id}/creators/{creator_id}/script
Returns the latest saved script version for one campaign creator (null before the first), whether a generation is queued or running, and whether the last one failed. Poll it after generate_creator_script. The script is generated from the creator's own posts and facts: labelled untrusted. Requires campaigns:read; the campaign must be visible to the key's member. Another workspace's (or a hidden) campaign or creator is 404.
get_creator_scriptcampaigns:read- admin, manager, scout, viewer
- Ignored (read)
- 1
script
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.creator_id path, requiredstring (uuid) — Roster creator id on that campaign.Responses
POST/api/v1/campaigns/{campaign_id}/creators/{creator_id}/script
Queues the next script version for one campaign creator, presenting the version and quote_token from preflight_creator_script. Pricing is the app's: a signed creator's first script is included (0 credits); every other version is 1 credit (script_regenerate), reserved now and settled when the script is saved (released if generation fails). The charge is keyed by the version, so a retry is never charged twice. Returns status queued (with job_id; poll get_creator_script), pending (a generation is already running), or completed (that version already exists: nothing charged). On a key left on "Ask for approval in TLNT" (the default) a charged regeneration is queued for an admin (202 pending_approval); an included first script runs directly. 409 quote_stale when the version moved on. Requires campaigns:write and discovery:spend, an Idempotency-Key, and a member who may manage the creator on that campaign.
generate_creator_scriptcampaigns:write+discovery:spend- admin, manager
- Runs directly; queued when the credential asks for approval for discovery_spend
- required
- 1
Input
campaign_id path, requiredstring (uuid)creator_id path, requiredstring (uuid)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.version body, requiredintegerquote_token body, requiredstring — The quote_token from preflight_creator_script.Responses
POST/api/v1/campaigns/{campaign_id}/creators/{creator_id}/script/preflight
Free. Answers which script version generate_creator_script would write next and what it costs: 0 credits for a signed creator's first script (it is included), 1 credit (script_regenerate) for any other version. Returns a quote_token (5 minutes, this key only) bound to that campaign creator and version: pass version and quote_token to generate_creator_script. Requires campaigns:write and discovery:spend and a member who may manage the creator on that campaign (403 otherwise). Another workspace's (or a hidden) campaign or creator is 404.
preflight_creator_scriptcampaigns:write+discovery:spend- admin, manager
- Ignored (read)
- 1
Input
campaign_id path, requiredstring (uuid) — Campaign id in this workspace.creator_id path, requiredstring (uuid) — Roster creator id on that campaign.