# API reference

Every endpoint, field and response of the export API. Generated from [openapi.yaml](/docs/openapi.yaml) (OpenAPI 3.1, also as [JSON](/docs/openapi.json)).

- **Base URL:** `https://global-api.attentionpanel.com`
- **Auth:** `Authorization: <api key>` on every request, no scheme prefix.
- **Body:** JSON in and out. Unknown request fields are rejected.
- **Errors:** `{ "statusCode": 400, "message": "FROM_DATE_NOT_ALLOWED" }`. The `message` is the code to branch on.

## Create an export

`POST /impressions/export`

Starts an export job for one platform, market and inclusive range of UTC dates.

Request body:

| Field | Type | Description |
|---|---|---|
| `device` | string · required | The platform. One of `mobile`, `desktop`. |
| `market` | string · required | The market. One of `semarket`, `nomarket`, `dkmarket`, `fimarket`. |
| `from_date` | date · required | `YYYY-MM-DD`, inclusive. Not before the key's earliest allowed date. |
| `to_date` | date · required | `YYYY-MM-DD`, inclusive. Not before `from_date`. |
| `include_html_metadata` | boolean | Desktop only. Adds `html_metadata` when the key is entitled to it. |
| `version` | string | Mobile only. The mobile data version; `v1` when omitted. `v2` data starts on a date set per deployment: an earlier `from_date` returns 400 `V2_FROM_DATE_NOT_AVAILABLE` with that date in `available_from`. One of `v1`, `v2`. |

Response 200:

| Field | Type | Description |
|---|---|---|
| `export_id` | string · required | Use in the other endpoints. URL-encode it in paths. |
| `status` | string · required | Always `RUNNING`. |
| `version` | string | The data version the job exports. One of `v1`, `v2`. |

Errors:

| Status · message | Cause |
|---|---|
| 400 (validation message) | Missing or unknown field, bad date, or `from_date` after `to_date`. |
| 400 FROM_DATE_NOT_ALLOWED | `from_date` is before the key's earliest allowed date. |
| 400 MAX_PARALLEL_RUNS_LIMIT_REACHED | The key already has its maximum number of running jobs for this platform, market and version. |
| 400 V2_FROM_DATE_NOT_AVAILABLE | `version` `v2` with `from_date` before the first day of v2 data, which `available_from` gives (`YYYY-MM-DD`). |
| 400 V2_ONLY_AVAILABLE_FOR_MOBILE | `version` `v2` with a device other than `mobile`. |
| 401 | No `Authorization` header. |
| 403 | Invalid key, or platform or market outside its entitlements. |

## Get an export

`GET /exports/{export_id}`

Returns the job's state, and the files once it has succeeded.

Response 200:

| Field | Type | Description |
|---|---|---|
| `status` | string · required | Only `RUNNING` changes. One of `RUNNING`, `SUCCEEDED`, `FAILED`, `CANCELLED`. |
| `version` | string | The data version the job exports. One of `v1`, `v2`. |
| `download_urls` | string[] | On `SUCCEEDED`. Presigned, one per file, valid 24 hours after completion. Send no `Authorization` header to them. |
| `failure_reason` | string | On `FAILED`: `NO_DATA` (no rows for the request) or `INTERNAL_ERROR`. One of `NO_DATA`, `INTERNAL_ERROR`. |

Errors:

| Status · message | Cause |
|---|---|
| 400 EXPORT_EXPIRED | The download URLs are older than 24 hours. Create a new export. |
| 404 | Unknown `export_id`, or one created with another key. |

## Cancel an export

`POST /exports/{export_id}/cancel`

Stops a running job.

Response 200:

| Field | Type | Description |
|---|---|---|
| `export_id` | string · required | The cancelled job. |
| `status` | string · required | Always `CANCELLED`. |

Errors:

| Status · message | Cause |
|---|---|
| 400 EXPORT_NOT_IN_CANCELABLE_STATE | The job is no longer running. |
| 404 | Unknown `export_id`, or one created with another key. |