API & export

1. 1.Sign in as the workspace owner and open Settings, then the API keys card.
2. 2.Name the key (for example “BI dashboard”) and choose Create key.
3. 3.Copy the key straight away. It starts with rs_live_ and is shown only once: RivalSweep stores a hash, not the key, so a lost key can only be replaced.

A workspace can hold up to 5 active keys. Revoke a key from the same card and it stops working immediately; revoked keys stay listed so you can see when they were last used.

Send the key as a Bearer token on every request. A missing, malformed or revoked key returns 401.

Authorization: Bearer rs_live_your_key

Requests are limited to 120 per minute per key; beyond that the API answers 429, so wait a moment and retry.

All four endpoints are GET.

List changes (JSON)

/api/v1/export/changes.json returns {generated_at, workspace, note, count, changes}, newest first.

curl -H "Authorization: Bearer rs_live_your_key" \
  "https://rivalsweep.com/api/v1/export/changes.json?importance=high&since=2026-10-01&limit=50"

List changes (CSV)

/api/v1/export/changes.csv takes the same filters and returns the same columns, flattened, as a file download. Cells that start with =, +, - or @are prefixed with an apostrophe so spreadsheets don't run them as formulas.

curl -H "Authorization: Bearer rs_live_your_key" \
  -o rivalsweep-changes.csv \
  "https://rivalsweep.com/api/v1/export/changes.csv?category=pricing"

One change, with the full diff

/api/v1/export/changes/<id>/ returns one change plus diff_text and structured_diff. An id outside your workspace returns 404.

curl -H "Authorization: Bearer rs_live_your_key" \
  "https://rivalsweep.com/api/v1/export/changes/00000000-0000-0000-0000-000000000000/"

Competitors and their pages

/api/v1/export/competitors.json returns each competitor with its approved monitored pages (url, page_type, last_crawled_at, last_change_at).

curl -H "Authorization: Bearer rs_live_your_key" \
  "https://rivalsweep.com/api/v1/export/competitors.json"

The two list endpoints accept these query parameters:

• since, until: an ISO date or datetime in UTC, applied to the detection time. A bare until date includes that whole day. Use Z, not +00:00, in URLs.
• category, importance, review_status, page_type: match exactly one value.
• competitor: a competitor id from competitors.json.
• q: text search in the change title and summary.
• limit: results to return, 100 by default, 1000 at most.

Without review_status every status is returned. Each change carries id, detected_at, title, summary, category, importance, review_status, confidence, the competitor and page, evidence_before, evidence_after, pricing_changes and possible_impact.

Every JSON response carries a note field:

"note": "possible_impact is AI inference; evidence_before/after and pricing_changes are the observed facts"

Treat evidence_before, evidence_after, pricing_changes and diff_text as what was observed on the page. The summary, category, importance and possible_impact fields are interpretation, and possible_impact in particular is a labeled AI inference, not a fact. Keep that distinction when you quote or forward the data.

A read-only MCP (Model Context Protocol) server exists for Claude Desktop, Claude Code and other MCP clients. Its tools mirror this API: public_radar reads the public live radar without a key; list_changes, get_change, list_competitors and watch_status read your workspace with the API key you give it through RIVALSWEEP_API_KEY. It stores nothing and sends the key only to rivalsweep.com.

It is not on a package index yet. Email [email protected] and we send you the package with install instructions for your client.

The JSON is designed to be consumed by agents as well as dashboards: stable field names, the evidence kept separate from the interpretation, and a note that tells a model which fields are facts. Give your assistant or script the base URL, the Bearer header and the endpoint list above, and have it call changes.json with a since filter. Ask it to cite evidence_before and evidence_after when it reports a change and to label possible_impact as inference.

Questions or something missing? Email [email protected].