API

Last updated August 25, 2026

A REST API for pulling your competitive intel into your own agents or tools, instead of a person reading the dashboard, and for pushing win/loss data in the moment a deal closes instead of batch-exporting a CSV later. Available on Plus and Advanced plans: generate a key from Settings → Developer.

Quickstart

Every request needs your key as a bearer token. This lists your tracked competitors:

curl https://www.ripplewatch.ai/api/v1/competitors \
  -H "Authorization: Bearer rw_live_..."

Authentication

Send your key as a bearer token on every request:
Authorization: Bearer rw_live_...

Keys are shown once at creation and never stored in plaintext: if you lose one, revoke it and generate a new one from Settings → Developer. Requests are rate-limited to 60/minute per key, tracked in a rolling 60-second window.

Endpoints

GET/api/v1/competitors

List every competitor tracked on your account, oldest first.

Example

curl https://www.ripplewatch.ai/api/v1/competitors \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": [
    {
      "id": "b3f1...",
      "name": "Xero",
      "domain": "xero.com",
      "category": "Accounting software",
      "pricing_url": "https://xero.com/pricing",
      "careers_url": "https://xero.com/careers",
      "created_at": "2026-06-01T12:00:00.000Z"
    }
  ]
}

GET/api/v1/competitors/:id

A single competitor, including its fact sheet (why you tend to win or lose deals against them, if generated).

Example

curl https://www.ripplewatch.ai/api/v1/competitors/b3f1... \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": {
    "id": "b3f1...",
    "name": "Xero",
    "domain": "xero.com",
    "category": "Accounting software",
    "pricing_url": "https://xero.com/pricing",
    "careers_url": "https://xero.com/careers",
    "fact_sheet_why_we_win": "...",
    "fact_sheet_why_we_lose": "...",
    "fact_sheet_generated_at": "2026-08-01T09:00:00.000Z",
    "created_at": "2026-06-01T12:00:00.000Z"
  }
}

GET/api/v1/signals

Scored and unscored signals across your competitors, newest first. Every field the dashboard shows for a signal is here, plus the competitor's name so you don't need a second lookup.

Query params

  • competitor_id (uuid) - Limit to one competitor. Ignored (returns an empty list) if it isn't one of yours.
  • type (string) - One of pricing, job_posting, review, news, funding, seo, product_change.
  • relevance_level (string) - One of High, Medium, Low.
  • since (date, YYYY-MM-DD) - Only signals that occurred on or after this date.
  • limit (integer) - Default 50, max 100.
  • offset (integer) - Default 0, for paging past limit.

Example

curl "https://www.ripplewatch.ai/api/v1/signals?relevance_level=High&limit=20" \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": [
    {
      "id": "9a2c...",
      "competitor_id": "b3f1...",
      "competitor_name": "Xero",
      "type": "pricing",
      "title": "Xero raised its Growth plan from $69 to $79/mo",
      "summary": "Detected on Xero's pricing page.",
      "url": "https://xero.com/pricing",
      "occurred_on": "2026-08-20",
      "scored": true,
      "relevance_level": "High",
      "relevance_score": 82,
      "relevance_reasoning": "...",
      "source": "pipeline",
      "created_at": "2026-08-20T13:04:11.000Z"
    }
  ],
  "count": 143,
  "limit": 20,
  "offset": 0
}

GET/api/v1/trends

Recurring win/loss themes identified across every logged win/loss reason, most-supported first, with any real tracked signals they connect to. Empty until you've generated trends at least once from the dashboard's Win/loss section.

Example

curl https://www.ripplewatch.ai/api/v1/trends \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": [
    {
      "id": "e71a...",
      "theme": "Price sensitivity",
      "summary": "Deals are being lost on price more than any other factor.",
      "won_count": 2,
      "lost_count": 7,
      "example_reasons": ["Went with the cheaper option", "Price was the deciding factor"],
      "related_signals": [
        { "signalId": "9a2c...", "relationNote": "Xero's recent price hike likely widened this gap." }
      ],
      "generated_at": "2026-08-18T10:00:00.000Z"
    }
  ]
}

GET/api/v1/momentum

A momentum score and label (e.g. Heating up, Steady, Cooling) for every tracked competitor, computed from hiring, pricing, sentiment-weighted press/funding coverage, and win/loss trend. Deterministic: no LLM cost, safe to poll.

Example

curl https://www.ripplewatch.ai/api/v1/momentum \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": [
    { "competitor_id": "b3f1...", "competitor_name": "Xero", "score": 42, "label": "Heating up" }
  ]
}

GET/api/v1/verdict

This week's synthesized takeaway (the same one-paragraph summary shown at the top of the dashboard) if one has been generated in the last 8 days. Returns null fields once it goes stale rather than serving week-old context as current.

Example

curl https://www.ripplewatch.ai/api/v1/verdict \
  -H "Authorization: Bearer rw_live_..."

Response

{
  "data": {
    "verdict": "Xero's price increase is your best opening this week...",
    "generated_at": "2026-08-24T12:00:00.000Z"
  }
}

POST/api/v1/win-loss

Push a single deal outcome in the moment it closes, instead of batch-exporting a CSV later. Matches competitor_name case-insensitively against your tracked competitors; a name that doesn't match becomes a suggested competitor instead of being rejected. Updates that competitor's Momentum win-rate trend immediately, returned in the response.

Body params

  • competitor_name (string, required) - Matched case-insensitively against your tracked competitors.
  • outcome (string, required) - One of won, lost.
  • reason (string) - Optional free text: why the deal went that way.

Example

curl -X POST https://www.ripplewatch.ai/api/v1/win-loss \
  -H "Authorization: Bearer rw_live_..." \
  -H "Content-Type: application/json" \
  -d '{"competitor_name": "Xero", "outcome": "lost", "reason": "Price was the deciding factor"}'

Response

{
  "matched": true,
  "imported": 1,
  "skipped": 0,
  "suggestedCompetitors": [],
  "momentum": { "score": 24, "label": "Heating up" }
}

Email win/loss data in

No integration or script needed: on Plus/Advanced plans, Settings → Developer shows a personal address of the form winloss+<accountId>@in.ripplewatch.ai. Forward a "we lost this deal" email there, or CC it from your CRM's outcome notification, and it runs through the same extraction pipeline as a CSV import: matched against your tracked competitors, or added as a suggested competitor if it isn't one yet.

Response shape

Every endpoint returns { data: ... }: an array for list endpoints, an object for single resources. /api/v1/signals additionally returns count (the total matching rows, not just this page), limit, and offset.

Errors

Errors return { error: string } with one of these statuses: