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

# API Overview

> Programmatic access to your Upstack Data pixel — authentication, base URLs, scopes, error format, and a curl quickstart.

The Upstack Data API lets you query your event data, list the measures catalog,
and manage dashboard views from anything that speaks HTTP. The same endpoints
power the in-app dashboard and the [`upstack` CLI](/cli/install).

<Tip>
  If you're scripting against Upstack from a terminal, prefer the [`upstack`
  CLI](/cli/install) — it wraps these endpoints, handles auth, and adds
  ergonomics like measure-title resolution.
</Tip>

## Base URL

All endpoints in this reference are relative to `https://api.upstackdata.com`, grouped by service path:

* `/db-mgmt/api/*` — analytics queries and the measures catalog.
* `/accounts/api/*` — dashboard view management.
* `/tr/api/*` — server-side event ingestion.

These surfaces share the same authentication.

## Authentication

Every request carries two headers:

| Header       | Value                                                              |
| ------------ | ------------------------------------------------------------------ |
| `x-api-key`  | Your Upstack API key. Starts with `upstack_`.                      |
| `x-pixel-id` | The pixel id this request targets. One key is scoped to one pixel. |

Mint an API key in the dashboard under **Settings → API Keys**. The raw key is
shown once at creation — store it securely; we keep only a hash.

```bash theme={null}
curl https://api.upstackdata.com/db-mgmt/api/measures \
  -H "x-api-key: upstack_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "x-pixel-id: 5f1e6a4f-..."
```

## Scopes

API keys carry one or more scopes. The required scope per endpoint is listed on
each endpoint's page.

| Scope              | Grants                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------ |
| `analytics:read`   | `POST /api/query`, `POST /api/query-attribution`, `POST /api/query-cohort-analysis`                                |
| `dashboards:read`  | `GET /api/dashboard/views` (list and individual)                                                                   |
| `dashboards:write` | `POST` / `PATCH` / `DELETE` on `/api/dashboard/views`, plus `/copy` and `/from-preset`. Implies `dashboards:read`. |
| `events:write`     | `POST /tr/api/events` — send server-side tracking events.                                                          |

The catalog endpoint (`GET /api/measures`) is ungated — any active key can read
the measures list. This unblocks discovery use cases (e.g. an LLM looking up
canonical measure ids before composing a query).

<Note>
  Older keys minted before May 2026 may carry legacy scopes `db_query` or
  `attribution_query`. These are auto-expanded to `analytics:read` at request
  time, so existing keys keep working without rotation. Rotate at your
  convenience to switch to the modern names.
</Note>

## Error format

Errors are JSON responses with a `message` field and the appropriate status code.

```json theme={null}
{
  "message": "API key does not have the dashboards:write scope"
}
```

400 responses on validated endpoints also include an `errors` array with per-field detail:

```json theme={null}
{
  "message": "Bad Request",
  "errors": [
    { "message": "name is required", "key": "name", "path": ["name"] }
  ]
}
```

| Status | Meaning                                                                                      |
| ------ | -------------------------------------------------------------------------------------------- |
| `200`  | Success.                                                                                     |
| `400`  | Validation error — see `errors` array.                                                       |
| `401`  | Missing/invalid `x-api-key` or `x-pixel-id`, revoked key, or expired key.                    |
| `403`  | Key is valid but doesn't carry the required scope.                                           |
| `404`  | Resource not found (or belongs to another pixel — we return 404 rather than leak existence). |
| `500`  | Server error. Retry; if persistent, file a support ticket with the request id.               |

## Quickstart

Discover what measures are available, then build a dashboard from three of them.

<Steps>
  <Step title="List measures">
    ```bash theme={null}
    curl https://api.upstackdata.com/db-mgmt/api/measures \
      -H "x-api-key: $UPSTACK_API_KEY" \
      -H "x-pixel-id: $UPSTACK_PIXEL_ID"
    ```

    Find the keys you want (e.g. `core.new_customer_roas`, `core.new_customer_mer`, `meta.cpm`).
  </Step>

  <Step title="Build a dashboard from those measures">
    ```bash theme={null}
    curl -X POST https://api.upstackdata.com/accounts/api/dashboard/views/from-preset \
      -H "x-api-key: $UPSTACK_API_KEY" \
      -H "x-pixel-id: $UPSTACK_PIXEL_ID" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "NC + Meta Pulse",
        "widgets": [
          { "measure": "core.new_customer_roas", "title": "NC ROAS" },
          { "measure": "core.new_customer_mer", "title": "NC MER" },
          { "measure": "meta.cpm", "title": "Meta CPM" }
        ]
      }'
    ```

    The response returns the full `DashboardView` with auto-laid-out sparkline widgets.
  </Step>

  <Step title="Open it in the dashboard">
    Sign in to [app.upstackdata.com](https://app.upstackdata.com) and pick the new
    view from the view dropdown.
  </Step>
</Steps>

For the same flow as a single CLI command, see [`upstack dashboard view build`](/cli/dashboard-view#build).