Skip to content

Apps and keys

GET /v1/apps

Scope read:creatives.

Terminal window
curl -s https://api.ad80.dev/v1/apps -H "Authorization: Bearer $AD80_API_KEY"
{
"apps": [
{
"appId": "com.example.news",
"name": "Example News",
"createdAt": "2026-10-20T08:00:00Z",
"lastUploadAt": "2026-10-28T09:12:44Z",
"sdkVersion": "0.2.0",
"policyVersion": 3,
"creativeCount": 412,
"playground": false
}
]
}

playground: true marks the organization’s Policy Playground app; leave it out of SDK lists. lastUploadAt is the last accepted upload from the SDK (null before the first). sdkVersion and policyVersion can be null.

GET /v1/apps/{appId}

Scope read:creatives. One app in the same shape. Poll it to wait for the first upload (lastUploadAt). 404 when the app does not exist in your organization.

POST /v1/apps

Scope manage:keys.

Terminal window
curl -s -X POST https://api.ad80.dev/v1/apps \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"appId": "com.example.news", "name": "Example News"}'
FieldRules
appIdRequired. The app’s id: the Android application id, or the iOS bundle identifier that the SDK sends. At least two segments separated by dots, each starting with a letter, then letters, digits or _. Up to 150 characters. A hyphen is not accepted, so a bundle identifier that contains one (which Apple allows) is rejected with 400 today.
nameOptional display name, up to 100 characters.

201 with the app. 409 when the app id already exists in your organization.

GET /v1/keys

Scope manage:keys. Lists upload keys (ingest) and API keys (client). Secrets are never returned, only a non-secret prefix (the first 12 characters).

{
"keys": [
{
"id": "ik_7",
"type": "ingest",
"prefix": "ad80_ik_Ab3x",
"label": "Release build",
"appId": "com.example.news",
"createdBy": "user:31",
"createdAt": "2026-10-20T08:01:00Z",
"lastUsedAt": "2026-10-28T09:12:44Z",
"expiresAt": null,
"revokedAt": null
},
{
"id": "ck_3",
"type": "client",
"prefix": "ad80_ck_Q9zL",
"label": "Nightly export",
"scopes": ["read:creatives", "read:verdicts"],
"createdBy": "user:31",
"createdAt": "2026-10-21T10:00:00Z",
"lastUsedAt": null,
"expiresAt": "2027-10-21T10:00:00Z",
"revokedAt": null,
"rotatedFrom": "ck_1"
}
]
}

lastUsedAt is updated at most once a minute.

POST /v1/keys

Scope manage:keys.

FieldMeaning
typeclient (default) or ingest.
labelOptional, up to 100 characters.
scopesClient keys: at least one scope. A key can only grant scopes it has itself (403 otherwise).
appIdIngest keys: the app the key uploads for (required unless rotating).
expiresInDaysOptional, 0 to 3650. 0 or absent: no expiry.
rotatesOptional id of an active key to replace, for example ik_7 or ck_3. The new key keeps the old key’s scopes or app.
graceHoursWith rotates: the old key expires this many hours later (0 to 8760). 0 or absent: the old key stays valid until you revoke it.

Create an upload key for an app:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"type": "ingest", "appId": "com.example.news", "label": "Release build"}'

Create a read-only API key that expires in a year:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"type": "client", "label": "BI export", "scopes": ["read:creatives", "read:verdicts"], "expiresInDays": 365}'

Rotate an upload key, keeping the old one valid for 30 days while the app update rolls out:

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys \
-H "Authorization: Bearer $AD80_API_KEY" -H "Content-Type: application/json" \
-d '{"rotates": "ik_7", "graceHours": 720}'

201 response. key is the secret and is shown only here:

{
"id": "ik_8",
"key": "ad80_ik_THE_NEW_SECRET",
"prefix": "ad80_ik_Zx81",
"expiresAt": null,
"note": "the key is shown once; store it now"
}

Client keys also return scopes. Creating an upload key on a plan without SDK integration answers 403 with entitlement: sdk_ingest.

POST /v1/keys/{id}/revoke

Scope manage:keys. id is ck_<n> or ik_<n>. The key stops working at once.

Terminal window
curl -s -X POST https://api.ad80.dev/v1/keys/ik_7/revoke -H "Authorization: Bearer $AD80_API_KEY"
{ "id": "ik_7", "revoked": true }

In rare cases the response adds warning: the revocation then takes effect within 30 seconds.