Canopy API Reference

All API requests must include an Authorization header with your API key. Keys begin with cnpy_ and are issued per account (not per seat).

Authorization: Bearer cnpy_<your-key>

Generate keys at Settings → API Keys. The full key is shown once only at creation time — store it in a secrets manager immediately.

Rate limits vary by endpoint. When exceeded the API returns 429 Too Many Requests with a JSON body explaining the limit and scope. No Retry-After header is currently emitted — use exponential backoff starting at 1 second.

All errors return JSON with at minimum an "error" string field.

Returns all competitors tracked by your account, with unread-change counts and last activity timestamp.

Headers

Query parameters

Response

{
  "competitors": [
    {
      "id": "cmp_abc123",
      "name": "Acme Corp",
      "website_url": "https://acme.example.com",
      "logo_url": "https://...",
      "description": "...",
      "software_type": "saas",
      "created_at": "2025-01-15T10:00:00Z",
      "unread_changes": 3,
      "total_changes": 42,
      "last_change_at": "2026-04-24T18:23:00Z"
    }
  ]
}

Returns a single competitor record with the same change-count aggregations as the list endpoint.

Headers

Path parameters

Response

{
  "competitor": {
    "id": "cmp_abc123",
    "name": "Acme Corp",
    "website_url": "https://acme.example.com",
    "google_news_query": "Acme Corp",
    "track_jobs": 1,
    "logo_url": "https://...",
    "description": "...",
    "founded_year": 2018,
    "employee_range": "51-200",
    "headquarters": "San Francisco, CA",
    "funding_stage": "Series B",
    "software_type": "saas",
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2026-04-20T09:00:00Z",
    "unread_changes": 3,
    "total_changes": 42,
    "last_change_at": "2026-04-24T18:23:00Z"
  }
}

Returns a unified historical event timeline for a competitor, sorted newest first. Sources include archived web snapshots, news articles, SEC financial filings, and legal cases.

Headers

Path parameters

Query parameters

Response

{
  "events": [
    {
      "type": "news",
      "date": "2026-03-10T00:00:00Z",
      "title": "Acme raises $40M Series B",
      "subtitle": "TechCrunch — tone: 0.8",
      "url": "https://techcrunch.com/...",
      "data": {
        "source": "TechCrunch",
        "toneScore": 0.8,
        "snippet": "..."
      }
    },
    {
      "type": "web",
      "date": "2026-02-14T00:00:00Z",
      "title": "Messaging changed",
      "subtitle": "\"The AI platform for enterprise teams\"",
      "url": "https://web.archive.org/...",
      "data": {
        "headline": "The AI platform for enterprise teams",
        "previousHeadline": "Workflow automation for teams",
        "url": "https://acme.example.com"
      }
    },
    {
      "type": "financial",
      "date": "2025-12-31T00:00:00Z",
      "title": "Q4 2025 Financials",
      "subtitle": "Q4 2025 — Revenue: $12.3M (+18% QoQ, +42% YoY)",
      "url": "https://sec.gov/...",
      "data": {
        "revenue": 12300000,
        "netIncome": 1100000,
        "rdExpense": 3200000,
        "filingType": "10-Q"
      }
    }
  ]
}

Returns the full dashboard data blob: all active competitors with aggregated change metrics, the 20 most recent changes across all competitors, and account-level stats.

Headers

Query parameters

Response

{
  "competitors": [
    {
      "id": "cmp_abc123",
      "name": "Acme Corp",
      "website_url": "https://acme.example.com",
      "active": 1,
      "unread_changes": 3,
      "high_priority_unread": 1,
      "changes_this_week": 7,
      "last_change_at": "2026-04-24T18:23:00Z"
    }
  ],
  "recentChanges": [
    {
      "id": "chg_xyz",
      "competitor_id": "cmp_abc123",
      "competitor_name": "Acme Corp",
      "type": "pricing",
      "title": "Pricing page updated",
      "summary": "Enterprise tier added at $499/mo",
      "importance": "high",
      "detected_at": "2026-04-24T18:23:00Z",
      "read": 0
    }
  ],
  "stats": {
    "totalCompetitors": 8,
    "competitorLimit": 20,
    "totalUnread": 14,
    "highPriority": 3,
    "changesThisWeek": 22,
    "changesLastWeek": 18,
    "mostActiveThisWeek": "Acme Corp",
    "plan": "scale"
  }
}

Submit a natural-language question about your competitors. Canopy retrieves semantically relevant intelligence from your account data and generates an answer using the configured AI model. Requires Starter plan or above.

Headers

Request body

Example request

curl -X POST https://yourcanopy.net/api/ask \
  -H "Authorization: Bearer cnpy_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"question": "What pricing changes have my competitors made in the last 30 days?"}'

Response

{
  "answer": "Three competitors updated their pricing in the last 30 days. Acme Corp added an Enterprise tier at $499/mo...",
  "sources": [
    {
      "type": "change",
      "competitorName": "Acme Corp",
      "title": "Pricing page updated",
      "detectedAt": "2026-04-24T18:23:00Z"
    }
  ],
  "scope": "global",
  "cached": false
}

Rate limit response (429)

{
  "error": "Rate limit: max 20 questions per hour per seat. Try again shortly.",
  "scope": "hourly",
  "limit": 20
}