> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognizo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> From zero to your first API call.

<Steps>
  <Step title="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.
  </Step>

  <Step title="Make a request">
    Send the key in the `X-API-KEY` header:

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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 }
    }
    ```
  </Step>

  <Step title="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.

    ```bash theme={null}
    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:

    ```json theme={null}
    {
      "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](/guides/metrics) before you chart or re-aggregate it.
  </Step>

  <Step title="Explore">
    Browse the [API Reference](/api-reference/introduction) and try any
    endpoint live from the console — or connect the
    [MCP server](/mcp/overview) so your AI assistant can call the API for you.
  </Step>
</Steps>

<Note>
  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.
</Note>