# Data API Quickstart

The Data API gives agencies, DSPs, and data partners read access to Trillboards audience intelligence: live audience snapshots, historical aggregations, semantic search over scene embeddings, and lookalike screen discovery. Use it for planning, attribution, and measurement workflows that do not need ad-serving control.

**Base URL:** `https://api.trillboards.com`

## 1. Get an API key

Data API keys have the prefix `tb_dat_` and are issued from the [portal](https://trillboards.com/developers). Keys are scoped; common scopes are `read:live`, `read:historical`, `read:semantic`, and `stream:live`. Each request must include the key in the `X-API-Key` header.

## 2. Make your first call

List the screens your key is authorized to see:

```bash
curl -s "https://api.trillboards.com/v1/data/screens?limit=5" \
  -H "X-API-Key: tb_dat_xxxxxxxxxxxx"
```

Success response:

```json
{
  "screens": [
    { "screen_id": "...", "mongo_screen_id": "...", "name": "Lobby #3",
      "venue_type": "fitness", "city": "Brooklyn", "country": "US", "status": "active" }
  ],
  "count": 1, "offset": 0, "limit": 5
}
```

If the `X-API-Key` header is missing or invalid, you get the canonical error envelope:

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "Invalid or inactive API key provided.",
    "request_id": "req_a1b2c3d4e5f6789012345678901234ab",
    "doc_url": "https://api.trillboards.com/docs/errors#invalid_api_key"
  }
}
```

Every 4xx/5xx response echoes `error.request_id` matching the `X-Request-Id` response header. Paste it into a support ticket and we can trace the request end-to-end.

## 3. Common errors

| `error.code` | HTTP | How to fix |
|---|---|---|
| `authentication_required` | 401 | Add the `X-API-Key` header. |
| `invalid_api_key` | 401 | Check the key you copied from the portal. Rotate if compromised. |
| `insufficient_permissions` | 403 | Your key is missing a required scope (for example, `read:historical`). Request an upgrade from your account manager. |
| `rate_limit_exceeded` | 429 | Back off using the `Retry-After` header; default limit is 60 req/min per key. |

## Next steps

- Full reference: [`/docs/data`](https://api.trillboards.com/docs/data)
- Error catalog: [`/docs/errors`](https://api.trillboards.com/docs/errors)
- FEIN query DSL: `POST /v1/data/query` for composable dimensions + measures
- Streaming: `GET /v1/data/stream` (Server-Sent Events, scope `stream:live`)