COMPETITIVE SIGNALS API · V1

Your verified record, addressable.

Programmatic access to competitor signals, briefings, and on-demand snapshots. Authenticate with a Bearer API key. All responses use the { data, meta } envelope; errors use { error: { code, message } }.

SHOW22 ENDPOINTS

Signals

SIGNALS

Competitor signal events

Tenant-scoped. Industry signals are excluded from this endpoint by design, as are briefing-only signals recorded below the notability floor.

competitorFilter to one tracked competitor.

sinceOnly signals observed after this timestamp.

typeOne of the sixteen competitive event types.

limitPage size.

cursorKeyset cursor from meta.next_cursor.

Competitors

COMPETITORS

Tracked competitors for your workspace

Everything your workspace currently watches.

Returns 201 on success. A 403 means the plan limit is reached or the tier is too low — not that the request was malformed.

Ownership is verified before deletion; a competitor outside your workspace returns 404, never 403.

Briefings

BRIEFINGS

Generated competitive briefings

Free keys receive briefing metadata; the synthesised summary is included from Pro upward.

sinceOnly briefings generated after this timestamp.

limitPage size.

cursorKeyset cursor from meta.next_cursor.

The whole briefing document, sections and citations included.

Snapshots

SNAPSHOTS

On-demand competitor page snapshots

Accepted with a job_id. The hourly cap is hard, because each accepted call triggers a real collection run.

Poll until the job resolves; an unknown job id returns 404.

Analysis

ANALYSIS

Grounded Layer-2 implications

Produced by the weekly analysis pass. Every claim carries basis_signal_ids naming the signals it was derived from; a claim whose citations cannot be resolved is discarded rather than published, so this endpoint never serves an unsourced claim.

competitorMatch either the subject directly or the basis signal.

subject_kindsignal id, competitor name, or dossier section key.

sinceOnly implications produced after this timestamp.

limitPage size.

Compare

COMPARE

Positioning gap matrix

The latest computed us-vs-them matrix. Read-only — it never triggers collection; the gap is computed weekly.

competitorTracked competitor to compare against.

period_weekISO week key, e.g. '2026-W25'. Defaults to latest.

Dossier

DOSSIER

Standing per-competitor dossiers

The last finalized dossier: sections, version number, generation metadata. A 404 is generic by design so competitor names never leak across tenants.

Recomposed from signals collected since the last finalization — what the next version will contain.

Every finalized version, newest first.

A specific finalized version by its number.

Pass view=live to render the uncommitted view instead of a finalized version.

Defaults to the latest version.

Recomposes and finalizes a new version immediately rather than waiting for the scheduled run.

Tokens are stored hashed, so the raw token is returned once at creation and cannot be recovered afterwards. An empty body creates a live link with the default 30-day expiry.

Active tokens, identified by hash. Raw tokens are never returned.

Revokes a share token immediately.

Usage

USAGE

API usage for the calling key

Counts for the key making the request, not the whole workspace.

MCP

Model Context Protocol server

Point any MCP client at this endpoint with a Vaarta API key and it can query your verified signal record directly. One JSON-RPC request per POST, one JSON response back, with no session to establish or tear down. Auth, usage logging and the per-key rate limit reuse the same middleware as /v1, and the RPM budget is shared.

Every claim the API returns carries the signal ids it was drawn from. If a claim cannot cite one, it is discarded at generation time rather than served.

How grounding works