Changes

Changes are the core output of Competiflow: interpreted diffs with severity, summary, recommended action, and evidence. This is what you read from the competitor inbox.

List changes

GET /v1/changes?workspace_id=:id

curl "https://api.competiflow.com/v1/changes?workspace_id=42&min_severity=medium&limit=25" \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY"

Response (200 OK):

{
  "changes": [
    {
      "id": 901,
      "competitor_id": 7,
      "competitor": "Example Co",
      "logo_url": "https://...",
      "monitor_id": 101,
      "monitor_type": "pricing",
      "severity": "high",
      "severity_score": 80,
      "summary": "Pro plan dropped from $99 to $79/mo",
      "recommended_action": "Review positioning against the new price point",
      "opportunity_score": 72,
      "review_status": "unreviewed",
      "category": "pricing",
      "direction": "retreated",
      "delta": { "added": 0, "removed": 0 },
      "created_at": "2026-07-14T12:30:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": 900,
  "meta": {
    "counts": { "unreviewed": 3, "acknowledged": 12, "dismissed": 5 },
    "max_unreviewed_severity": "high"
  }
}

See Pagination for cursor usage.

Derived fields

Some list fields are derived from the change's field diffs:

Get change

GET /v1/changes/:id

GET /v1/changes/:id?include=capture,capture_markdown,raw_diff

Optional include values (comma-separated):

When both capture and capture_markdown are requested, the API returns one capture object with fields and markdown.

Returns every list field plus the interpreted evidence chain:

{
  "change": {
    "id": 901,
    "competitor": "Example Co",
    "monitor_type": "pricing",
    "severity": "high",
    "summary": "Pro plan dropped from $99 to $79/mo",
    "recommended_action": "Review positioning against the new price point",
    "why_it_matters": "Direct price undercut on your core tier",
    "field_diffs": [
      {
        "op": "updated",
        "change_type": "price_decrease",
        "path": "plans[Pro].price",
        "tier": "alertable",
        "old": { "price": "$99/mo" },
        "new": { "price": "$79/mo" }
      }
    ],
    "clusters": [
      {
        "headline": "Pro pricing cut",
        "meaning": "Example Co reduced its Pro tier price.",
        "diff_indexes": [0]
      }
    ],
    "evidence": {
      "diffs": [
        {
          "op": "updated",
          "change_type": "price_decrease",
          "path": "plans[Pro].price",
          "tier": "alertable"
        }
      ]
    },
    "enrichment": {
      "seo_opportunity": { "keywords": [] }
    },
    "interpreted_by": "gpt-4o-mini",
    "interpreted_at": "2026-07-14T12:30:00Z",
    "source_url": "https://example.com/pricing",
    "raw_diff_available": true
  }
}

field_diffs entries are generated by the interpreter; the top-level keys
(op, change_type, path, tier, old, new) are stable, but the inner
shape of old/new varies by monitor type. evidence and enrichment are
objects, not arrays.

Severity levels

Update review status

PATCH /v1/changes/:id

curl -X PATCH https://api.competiflow.com/v1/changes/901 \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"review_status": "acknowledged"}'

Review status

Set review_status with PATCH /v1/changes/:id. Filter the feed with the review_status query param on list.