TARS internal admin API

​

Authentication and errors

• Invalid query parameters return 400.
• A caller without SuperAdmin access receives 403.
• An unavailable marketing database returns 503 without exposing connection details. The failure is logged and reported to Sentry.
• Journey responses can be partial: each unavailable tile has { "status": "unavailable", "data": null }. Treat that state as unknown, not as a zero metric.

​

Manual sales meeting notes and transcript intake

• POST /api/v2/admin/tars/meetings/transcript-intake accepts an exact canonical orgRef, exactly one attachment or notionUrl, and an optional conversationUid. An attachment contains filename, mimeType, and base64-encoded content. The route reads a Notion page as Markdown, including its meeting transcript when available, and rejects partial page responses. It returns the stable transcriptId, whether the intake was a duplicate, the resolved organisation, and every extracted commercial or operational claim with its review status.
• POST /api/v2/admin/tars/meetings/transcript-intake/review accepts that transcriptId, the same orgRef, and one decision for every pending claim. Each decision identifies its claimUid and chooses keep or discard; a kept claim may also replace the bounded statement or correct its kind to commercial or operational. A request contains 1 to 50 decisions and the response reports the approved and rejected totals with the resulting claims.

​

Notion rollout check

​

Marketing email creative library

• tars_get_marketing_email_library loads templates, assets, and themes.
• tars_get_marketing_email_template loads one template and its version history.
• tars_preview_marketing_email_version renders one saved version with sample merge-token values.
• tars_create_marketing_email_copy_draft creates a reusable copy draft or saves a new version of an existing draft; older versions remain unchanged.
• tars_approve_marketing_email_version approves a draft version. The author cannot approve their own draft.

​

Approved deck modules

• tars_get_approved_deck_modules loads modules, claims, assets and PDF imports.
• tars_get_approved_deck_module loads one module’s revision history and HTML.
• tars_create_approved_deck_claim, tars_approve_deck_claim and tars_remove_approved_deck_claim maintain sourced product claims.
• tars_save_approved_deck_module_draft saves structured copy and renders a new immutable preview.
• tars_approve_deck_module_revision publishes the latest draft after checking its live sources.
• tars_remove_approved_deck_module deletes a never-published module or revokes a published one.
• tars_remove_approved_deck_asset deletes an unused pending image or revokes a used or approved one.

​

Prospect proposal preparation

• POST /api/v2/admin/commercial-offers/preview returns the resolved preview snapshot as JSON.
• POST /api/v2/admin/commercial-offers/preview/document.pdf renders that same snapshot as a downloadable PDF.

{
  "schemaVersion": 1,
  "organizationName": "Example Publisher",
  "currency": "USD",
  "sourceRateCardId": "8",
  "sourcePlanId": "9",
  "narrative": {
    "documentTitle": "Proposal for Example Publisher",
    "executiveSummary": "A source-grounded summary for the prospect.",
    "scope": {
      "included": ["One included outcome"],
      "exclusions": ["One explicit exclusion"]
    }
  }
}

​

Prospect proposal save

• tars_preview_prospect_proposal_save is read-only. Give it the company name and, for customised terms, a customisation in the shape Commercial Offers are authored with (adjustments and packageOverrides). Leave the customisation out to save the published terms. It composes the proposal the way a save does, using the plan and currency of the organisation’s current proposal unless you name a plan. A first proposal names the plan by display name or plan code in plan (for example Listing + Distribution, case does not matter) and the currency; no Rate Card or plan id is needed, and the plan is looked up on the Rate Card in effect now. With no plan, or a name that matches none or several, nothing is reviewed or saved and the response lists that Rate Card’s plans (up to 50) to choose from. sourceRateCardId and sourcePlanId still work. It returns each customised term beside its published default, which the server works out from the source plan, the published publishedProposal to base a proposal override on, a contentDigest and the currentVersionId the save would replace. A price change must also carry a proposal override with payment choices that match the new price, or the review is refused with the reason. A caller-supplied default is refused.
• tars_apply_prospect_proposal_save saves the version after a person confirms the exact review. It repeats the reviewed orgRef, plan, currency and customisation, with currentVersionId as expectedCurrentVersionId, contentDigest as expectedContentDigest and confirmed: true. Nothing is saved if a newer version was saved since the review or the proposal now composes differently. Saving the same content again records nothing new.

​

Prospect proposal review

• tars_preview_prospect_proposal_review is read-only. Give it the company name. It returns the version, the narrative, every public source with its statement and URLs, the published terms in full and each customised term beside its published default, all shown in full, and whether an approved commercial exception covers exactly those terms. Customised terms with no matching approval are blocked, and the review points to tars_request_commercial_exception.
• tars_apply_prospect_proposal_review marks the version reviewed after a person confirms that exact content. It repeats the reviewed orgRef and proposalVersionId, with the digest as expectedContentDigest and confirmed: true. It is refused if the saved content changed, a newer version replaced it, or customised terms have no approval. A proposal too large to show in full is refused rather than reviewed unseen. It issues nothing and sends nothing; the signup link tools are the next step.

​

Prospect signup link preparation

• tars_preview_prospect_signup_link is read-only. Give it the company name (or an orgRef from an earlier ambiguous result), the recipient’s exact recipientEmail, and optionally the prospect’s domain and expiresInDays (1 to 30, default 14). It resolves the organisation, reads its confirmed domain, its latest saved and reviewed proposal version and its latest signup link, and returns one review: recipient, whether an account or billing organisation exists, proposal version, plan, price, term and renewal, and any warnings or blockers. A missing email is reported as a missing input, not an error. An ambiguous or unknown company returns resolved: false with the outcome.
• tars_apply_prospect_signup_link creates the link after a person confirms the exact review. It repeats the reviewed orgRef, recipientEmail, expiresInDays, revision as expectedRevision and the review text as expectedConfirmationSummary, with confirmed: true. If the proposal, plan, recipient, organisation, account state or latest link changed since the review, nothing is created and a new review is required.

​

Customised terms approval

• tars_preview_commercial_exception is read-only. Give it the company name. It reads the customised terms saved on the organisation’s latest proposal version (save them first with tars_apply_prospect_proposal_save) and returns each changed term beside its published default, which the server works out from the source plan, with a commercialDigest. Terms passed as customisation must equal the saved ones, because an approval for different terms would never match the version; otherwise the review is refused. A caller-supplied default is refused.
• tars_request_commercial_exception records the request after a person confirms the review. It repeats the reviewed orgRef and proposalVersionId, a reason, the digest as expectedCommercialDigest, and confirmed: true; the terms are the ones saved on that version, so none are entered again. Nothing is recorded if the terms no longer produce that digest, and nothing is approved by asking.
• tars_list_commercial_exceptions lists requests, by default the PENDING ones, each with the organisation, proposal version, changes beside their defaults, reason and digest. Filter by status or company, or read one by requestId.
• tars_decide_commercial_exception approves or rejects one request with a reason and confirmed: true. It is refused for anyone who is not a current approver, for the person who asked, for a request already decided and for a proposal version that has been replaced.

• tars_list_commercial_exception_approvers is read-only. It lists each approver with name, email, when they were added and by whom. includeRemoved adds the 20 most recent removals and reports when older ones are not shown.
• tars_preview_commercial_exception_approver_change is read-only. Give it action (add or remove) and person, an email or a name. It shows exactly who would change and the approver count before and after. A name must match exactly one Scope3 staff member; if it matches several it lists them and chooses nobody. A person with no platform user must sign in once before they can be added.
• tars_apply_commercial_exception_approver_change records the change after a person confirms the preview. It takes action, the person email from the preview, a reason and confirmed: true. It is safe to repeat: adding a current approver or removing someone who is not one succeeds and reports no change. Every change is audited with who made it and why.

​

Customer domain approval

• An unknown account returns 404, and an account with no registered domain returns 400 (MCP: NOT_FOUND, VALIDATION_ERROR). A caller without SuperAdmin access receives 403; the MCP tool is not listed for them.
• A successful approval returns the account id, its customerDomain, and customerDomainApproved: true. The MCP tool also returns resolvedRequestCount.
• Approving closes the account’s open attestation request for that domain. The request is closed after the approval is saved, so a failure to close it does not undo the approval; approving again closes anything left open. Login access and account membership do not change, and the Linear ticket behind the escalation is not closed.
• Approving writes an audit entry when it is done through the MCP tool.

​

Product map verification

• A passed newest record on a capability that reads built makes it read tested, with stageBasis: verification. A failed newest record leaves it at built, which drops a tested capability back. A hand-set beta or GA from a feature’s maturity stays above tested, so a record there moves nothing. A capability whose own ticket reopens reads what the ticket rules give, whatever record is on file.
• tars_get_product_map returns the newest record of each capability as latestVerification (result, bar, evidenceUrl, who recorded it and when), passed or failed, with countsTowardStage saying whether it decided the stage.
• A value that is not a node id in the product architecture returns VALIDATION_ERROR, as does a building block or an area: only a capability can be verified.
• A capability that does not read built yet (no stage, planning, or in progress) cannot be verified: the review reports canApply: false with the reason, and apply returns CONFLICT.
• Apply returns CONFLICT when the review is stale: the capability’s stage or newest record changed since the review, or someone recorded in the meantime. Review again and confirm the new review.
• A caller without SuperAdmin access is refused and the tools are not listed for them. A caller with no signed-in person is refused on apply.
• Applying writes an audit entry.

​

Buyer journey and meeting speaker identities

• The writes change records inside TARS only. They send no email, Slack message or Linear item and create no customer account.
• Each write needs the caller’s email and writes an audit entry.
• Company names, domains, contact details, form answers, meeting names and speaker labels are written by buyers or come from transcripts. The tools return them fenced as untrusted data.

​

Your TARS connections

• Mail and calendar status is the status last recorded. A sign-in finished in the last few minutes shows pending until the TARS connections page is opened, and a connection that has just stopped working shows its old status until the next background sweep.
• Connecting for knowledge capture is offered only to staff in the TARS email pilot, and connecting a calendar only to staff in the TARS calendar pilot.
• The actions listed are the only ones the write tools below accept. The TARS connections page does the same work for the web.
• A connection’s health error comes from the provider and is returned fenced as untrusted data.

​

The Connections widget

• Your connections: GitHub, Outlook mail and Outlook calendar, connected with your own account and disconnected any time.
• On for everyone: Slack, Linear and Roam, which have no individual opt-out.

• The widget decides no rules. It reads the view through the app-only tars_get_my_connections_view, which returns the same result as tars_get_my_connections, and offers only the actions each source lists. Unlike the model-visible read, it does not fence the provider’s health error, because the widget renders it as plain text for its owner.
• Sign-in opens in a new tab through the host, never inside the widget. The widget reads the status again when you return to it, so a finished sign-in shows without reloading.
• GitHub connects on the TARS connections page, which the widget opens in a new tab. The /tars/connections page itself is unchanged.

​

Acting on your connections

• A tool is refused with a CONFLICT error that names the source, the action, the source’s status and the actions available now, unless actions from tars_get_my_connections lists the action. This also covers the pilots: knowledge capture is refused for staff outside the TARS email pilot, and a calendar connect for staff outside the TARS calendar pilot.
• GitHub cannot be disconnected here, and the sources on for everyone have no actions.

​

Choosing orgs for a knowledge-capture mailbox

• Orgs this mailbox captures. The chosen orgs, each with Remove. Find an org by name (two letters or more) and Add it. An org that a SuperAdmin has opted out of email capture is marked and is skipped whatever you chose.
• Check a counterparty. A dry run of the routing decision for a domain or up to ten email addresses. It says whether the mailbox would capture the thread and, if not, why, for example: not chosen, opted out, not an active customer or watched org, ambiguous, or no match. It writes nothing.
• What your inbox has shared. Lifetime totals and the claims the mailbox has minted, the newest 50 at most; the Task says when older ones are not listed. A pending claim can be approved, edited and approved, or rejected. A committed claim can be retracted, and stays in the ledger marked Retracted.

• Every one is refused with a CONFLICT error unless actions from tars_get_my_connections lists choose_orgs for Outlook mail. A mailbox connected for email sequences only, one that is not connected, and one whose sign-in is pending or needs a reconnect are all refused. Changing a mailbox to email sequences only, or disconnecting it, clears its chosen orgs.
• tars_manage_mailbox_orgs behaves as before. In a SuperAdmin TARS session it lists, adds and removes the same chosen orgs by org name or reference. The widget is the way to do it from Claude, ChatGPT and TARS chat when you want to see the orgs and the ledger.

​

SEO overview

• freshness: latest loaded date, row count, and synchronization time;
• window: the effective and available date bounds;
• kpis: current and prior impressions, clicks, click-through rate, and average position;
• trend: daily performance;
• topPages, topQueries, and pageQueries;
• opportunities: page/query pairs with at least 10 impressions whose impression-weighted average position is between 4 and 10, ordered by impressions.

​

Answer-engine visibility

​

Website journeys

​

Data-source configuration

• MARKETING_DATABASE_URL: isolated scope3_marketing connection. Use a role with SELECT-only grants; the pool also sets PostgreSQL sessions read-only.
• MARKETING_DB_POOL_MAX, MARKETING_DB_IDLE_TIMEOUT_MS, MARKETING_DB_CONNECTION_TIMEOUT_MS, MARKETING_DB_STATEMENT_TIMEOUT_MS: optional pool limits and timeouts.
• POSTHOG_API_KEY and POSTHOG_MARKETING_PROJECT_ID: marketing-site HogQL reads.
• POSTHOG_API_KEY_INTERCHANGE and POSTHOG_INTERCHANGE_PROJECT_ID: Apostra signup-attribution reads.

​

Announcement scheduling and threaded replies

​

Scheduling a draft

​

Kind: awareness or action required

​

Sending is at-most-once

​

Thread replies

​

What the send response reports

​

How replies are counted in reporting

​

Mailbox sequences that stop when a requirement is met

• agentId: the sales agent’s public id, as the admin agent tools show it.
• check: a dated capability check: canonical_creatives, reliable_reporting, compact_lifecycle or webhook_signing.

​

Recording an opt-out from a reply