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

Body field	Type	Required	Description
`name`	string	yes	Display name

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.

Update workspace

PATCH /v1/workspaces/:id

Send only the fields you want to change.

Body field	Type	Description
`name`	string	New display name. Cannot be blank.
`product_url`	string or null	Your own product's URL, used for `why_it_matters` on changes. `null` clears it.
`status`	`active` or `paused`	Pauses or resumes every monitor in the workspace. History is kept.

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

Response (200 OK) is the same shape as Get workspace, so monitors_paused shows the result of a pause. Validation errors return 422 with validation_failed, and nothing is changed: an invalid name does not leave monitors paused.

Delete workspace

DELETE /v1/workspaces/:id

Permanently deletes the workspace with its competitors, monitors, snapshots, and changes. To stop checks and keep history, update the workspace with status: paused instead.

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

Response (200 OK):

{ "success": "Workspace removed." }

Status	Code	When
`409`	`discovery_in_progress`	A competitor in the workspace is still being discovered. Wait for it, or delete the competitor in `active_competitor_id` first.
`409`	`workspace_in_use`	The workspace powers a public embed.
`404`	`not_found`	No workspace with that id belongs to you.

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.