Competitors

Competitors are tracked by homepage URL. When you add one, Competiflow runs grounded discovery to find monitorable surfaces (pricing, blog, changelog, docs, homepage) and seeds baseline checks.

List competitors

GET /v1/workspaces/:workspace_id/competitors

curl https://api.competiflow.com/v1/workspaces/42/competitors \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY"

Response (200 OK):

{
  "competitors": [
    {
      "id": 7,
      "name": "Example Co",
      "homepage_url": "https://example.com",
      "domain": "example.com",
      "slug": "example-co",
      "logo_url": "https://...",
      "discovery_status": "completed",
      "discovered_at": "2026-07-02T09:00:00Z",
      "created_at": "2026-07-02T08:55:00Z",
      "monitors": [
        {
          "id": 101,
          "name": "Pricing",
          "monitor_type": "pricing",
          "status": "active",
          "cadence": "daily"
        }
      ]
    }
  ]
}

Add competitor

POST /v1/workspaces/:workspace_id/competitors

curl -X POST https://api.competiflow.com/v1/workspaces/42/competitors \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://linear.app", "monitor_types": ["pricing", "changelog"]}'

Response (202 Accepted):

{
  "status": "discovering",
  "url": "https://linear.app",
  "competitor": {
    "id": 8,
    "name": "Linear",
    "discovery_status": "running",
    "homepage_url": "https://linear.app"
  }
}

Discovery is asynchronous. Poll discovery status or list competitors until discovery_status is completed.

Posting the same homepage URL again returns 200 OK with the existing competitor and does not start a second discovery run.

A workspace runs one discovery at a time. If a different competitor is still discovering, the request returns 409 discovery_in_progress with active_competitor_id in the error body so you know which competitor to poll.

Update competitor

PATCH /v1/competitors/:id

Delete competitor

DELETE /v1/competitors/:id

Removes the competitor, all its monitors, snapshots, and changes. This cannot be undone.

Get competitor

GET /v1/competitors/:id

Returns competitor detail including notes, monitors, and discovery fields.

Discovery status

GET /v1/competitors/:id/discovery_status

{
  "discovery_status": "completed",
  "competitor": { "id": 8, "name": "Linear", "discovery_status": "completed" }
}

Possible discovery_status values: pending, running, completed, failed.

Checks

Adding a competitor uses checks for discovery and baseline checks. See Billing.