Skip to main content
TARS uses internal REST endpoints and MCP tools for operator-only work. They are available only to authenticated Apostra SuperAdmins and are not part of the customer-facing Buyer or Seller API. The Marketing mandate at /tars/mandates/marketing reads from three of these REST endpoints. It combines search engine visibility, answer-engine visibility, website journeys, and the existing canonical buyer-lead view. The standalone marketing admin remains available until a later retirement slice.

​
Authentication and errors

All REST endpoints use the normal API session or bearer-token authentication and require the superAdmin role. Internal MCP tools are listed only for a directly authenticated SuperAdmin and re-check that access when called.
  • 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.
Dates use YYYY-MM-DD. Custom from and to values are inclusive, must be provided together, and take precedence over window.

​
Marketing email creative library

The Email library stores reusable drafts, approved creative, uploaded assets, themes, previews, and immutable version history. It does not choose an audience, enrol recipients, send email, or show delivery and sent-email history. Those operations belong to separate sequence and delivery surfaces. Use the model-visible tars_open_marketing_email_library tool to ask a compatible TARS host to display the library. Its structured response includes template, asset, and theme counts plus a bounded summary of the latest template versions. A tool response confirms only that the host was asked to open the library; it does not prove that the widget rendered. The widget uses these app-only tools internally:
  • 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. The editor can place one active library image after the copy; older versions remain unchanged.
  • tars_approve_marketing_email_version approves a draft version. The author cannot approve their own draft.
All six tools require a directly authenticated SuperAdmin. They are not advertised to delegated service principals. Models should call only the owner tool, tars_open_marketing_email_library; the widget owns the five app-only calls. The supporting REST surface is rooted at /api/v2/admin/marketing/email-library. It is an internal Admin UI contract, uses the same SuperAdmin boundary, and exposes library reads, template and version writes, preview rendering, approval, and bounded asset upload. Invalid input returns 400, unauthenticated calls return 401, and authenticated callers without SuperAdmin access receive 403.

​
Prospect proposal preparation

tars_open_prospect_proposal_authoring is the read-only handoff from one TARS organisation to the existing Commercial Offer authoring view. Supply at least one of orgRef, orgName, or customerId. When a Harvian handoff must be checked, also supply its exact customerId, protected userRef, or both under harvian. The tool resolves the existing organisation and canonical billing customer. It returns one authoring URL when the match is safe. Otherwise it returns explicit not-found, ambiguous Harvian, or missing-billing-customer blockers. It never creates an account, research question, proposal, offer, Page, or customer, and does not return contacts, interaction text, or private evidence. The existing Commercial Offer service provides two matching preview routes:
  • POST /api/v2/admin/storefront-rate-cards/commercial-offers/preview returns the resolved preview snapshot as JSON.
  • POST /api/v2/admin/storefront-rate-cards/commercial-offers/preview/document.pdf renders that same snapshot as a downloadable PDF.
Both routes accept the same strict body:
effectiveAt is optional and selects the published plan effective at that ISO timestamp. The narrative is optional and bounded. Callers cannot submit evidence through these routes; trusted evidence must come from the existing Customer Knowledge path. Previewing is non-mutating. Pricing, payment choices, term, support and entitlements come from the selected published plan. The response is marked as unissued, uses Cache-Control: private, no-store, and creates no customer, offer, entitlement revision or acceptance record. Formal issuance continues through the existing Commercial Offer authority.

​
SEO overview

GET /api/v2/admin/marketing/seo The response contains:
  • 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.
Query rows include rank tier, tier movement, zero-click and AI-query flags, and an at-risk signal. The first contract intentionally excludes live metadata health and the model-generated digest from the legacy dashboard.

​
Answer-engine visibility

GET /api/v2/admin/marketing/aeo The response supplies its fetch time and effective range, source status, prompt/run totals, current and prior primary-brand mention rates, share of voice by brand, performance by model, and the most-used citation URLs.

​
Website journeys

GET /api/v2/admin/marketing/journeys The response supplies its fetch time and effective range, overall source status, current/prior traffic and conversion KPIs, source breakdowns, homepage and converting paths, preview/contact/storefront funnels, and storefront signup attribution. Each tile reports its own availability.

​
Data-source configuration

The API process owns all credentials. The browser never receives database or PostHog keys.
  • 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.
Missing PostHog keys degrade the affected journey tiles instead of fabricating zero values. Marketing database access has no fallback to the application or ledger databases.