Quickstart
Get from zero to your first competitor change in four API calls.
1. Create an API key
Sign in at competiflow.com, open Settings → API keys, and create a key. It looks like sk_live_ followed by 48 hex characters. Store it securely.
2. Create a workspace
A workspace groups competitors for one product or market.
```bash
curl -X POST https://api.competiflow.com/v1/workspaces \
-H "Authorization: Bearer $COMPETIFLOW_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name": "My product"}'
```
```python
import os, requests
r = requests.post(
"https://api.competiflow.com/v1/workspaces",
headers={"Authorization": f"Bearer {os.environ['COMPETIFLOW_API_KEY']}"},
json={"name": "My product"},
)
print(r.json())
```
```ruby
require "net/http"
require "json"
uri = URI("https://api.competiflow.com/v1/workspaces")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV['COMPETIFLOW_API_KEY']}"
req["Content-Type"] = "application/json"
req.body = { name: "My product" }.to_json
puts Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |http| http.request(req) }.body
```
Response (201 Created):
{
"workspace": {
"id": 42,
"name": "My product",
"slug": "my-product",
"created_at": "2026-07-14T10:00:00Z"
}
}
Save the id — you will pass it as workspace_id in later calls.
3. Add a competitor
Discovery runs asynchronously. Competiflow finds pricing, blog, changelog, docs, and homepage surfaces and seeds baseline checks.
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://example.com"}'
Response (202 Accepted):
{
"status": "discovering",
"url": "https://example.com",
"competitor": {
"id": 7,
"name": "Example",
"discovery_status": "running",
"homepage_url": "https://example.com"
}
}
Poll GET /competitors/7/discovery_status until discovery_status is completed.
4. Read changes
Once monitors run, list interpreted changes for the workspace:
curl "https://api.competiflow.com/v1/changes?workspace_id=42&limit=10" \
-H "Authorization: Bearer $COMPETIFLOW_API_KEY"
Response:
{
"changes": [
{
"id": 901,
"competitor": "Example",
"monitor_type": "pricing",
"severity": "high",
"summary": "Pro plan dropped from $99 to $79/mo",
"recommended_action": "Review positioning against the new price point",
"review_status": "unreviewed",
"created_at": "2026-07-14T12:30:00Z"
}
],
"has_more": false,
"next_cursor": null
}
Fetch full evidence with GET /changes/901.
Next steps
- Workspaces and Digest for overview data
- MCP server for Cursor / Claude agent integration
- Billing for checks and plan limits