Quickstart

Create an API key

In the Cognizo dashboard, open Settings → API Keys, click Create key, name it, and copy the secret. The full key (starting cog_sk_) is shown once — store it somewhere safe. It inherits your organization’s access, so it can reach every brand your org owns.

Make a request

Send the key in the X-API-KEY header:

curl https://core.cognizo.ai/api/v2/brands \
  -H "X-API-KEY: YOUR_API_KEY"

You’ll get your brands back in the standard envelope:

{
  "data": [
    {
      "id": "b1a2c3d4-…",
      "name": "Acme",
      "domains": ["acme.com"],
      "status": "completed",
      "visibility": 42.1,
      "mode": "diy"
    }
  ],
  "meta": { "page": 1, "page_size": 25, "total_items": 1, "total_pages": 1 }
}

Pull a metric

Once you have a brand id, fetch its visibility. The window defaults to the last 30 days; pass filter[ran_at_start] / filter[ran_at_end] to change it and filter[granularity] to change the bucket size.

curl "https://core.cognizo.ai/api/v2/brands/BRAND_ID/visibility?filter[granularity]=week" \
  -H "X-API-KEY: YOUR_API_KEY"

You get one aggregate row plus a time series, each listing your brand and its competitors:

{
  "data": {
    "metric_type": "visibility",
    "date_range": ["2026-07-06T00:00:00Z", "2026-08-05T23:59:59Z"],
    "aggregate_metrics": {
      "start_date": "2026-07-06",
      "values": [
        { "brand_name": "Acme", "value": 42.1, "diff": 3.4, "rank": 1, "is_target": true },
        { "brand_name": "Globex", "value": 30.8, "diff": -1.2, "rank": 2, "is_target": false }
      ]
    },
    "time_based_metrics": [ ]
  }
}

value is a 0–100 percentage here — but not for every metric. Read Metrics & units before you chart or re-aggregate it.

Explore

Browse the API Reference and try any endpoint live from the console — or connect the MCP server so your AI assistant can call the API for you.

Keys are scoped to your organization, not a single brand — which brands you can reach is determined by what your org owns, exactly like the app.

Get started

Guides