Workspaces

A workspace groups competitors for one product, market, or GTM motion. Most API calls are scoped to a workspace via workspace_id.

List workspaces

GET /v1/workspaces

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

Response (200 OK):

{
  "workspaces": [
    {
      "id": 42,
      "name": "My product",
      "slug": "my-product",
      "created_at": "2026-07-01T08:00:00Z",
      "needs_review_count": 3,
      "max_unreviewed_severity": "high",
      "competitors_count": 4,
      "monitors_total": 18,
      "monitors_paused": 0
    }
  ]
}

Get workspace

GET /v1/workspaces/:id

Returns the same shape as a list item with competitor logos (up to 12).

Create workspace

POST /v1/workspaces

curl -X POST https://api.competiflow.com/v1/workspaces \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Enterprise segment"}'

Response (201 Created). Create returns the compact workspace summary — the
review/competitor/monitor counts appear on list and get:

{
  "workspace": {
    "id": 43,
    "name": "Enterprise segment",
    "slug": "enterprise-segment",
    "created_at": "2026-07-14T10:00:00Z"
  }
}

Validation errors return 422 with validation_failed.

Refresh workspace

POST /v1/workspaces/:id/refresh

Queues on-demand checks for every active monitor in the workspace. Pass competitor_id in the body to refresh one competitor only.

curl -X POST https://api.competiflow.com/v1/workspaces/42/refresh \
  -H "Authorization: Bearer $COMPETIFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Response (202 Accepted):

{
  "status": "queued",
  "count": 12,
  "skipped": 1,
  "skipped_ids": [105]
}

Workspace digest

See Digest for GET /v1/workspaces/:id/digest.

Plan limits

Each plan caps workspaces and monitors. See Rate limits and Billing.