Apogee REST API

Base URL and versions

Two routes need no key: GET / (the version and links) and GET /openapi.json (the document), both readable from any page.

curl https://api.apogee.ad/api/v1/

Requests and answers

• Bodies are JSON (UTF-8), 2 MB at most. A field the route does not know is refused (400 validation_failed): send only the documented ones. Ignore the fields of an answer you do not know.
• Every answer carries X-Request-Id (give it to support), Apogee-Version, and the rate-limit headers RateLimit and RateLimit-Policy; a 429 adds Retry-After (rate limits).
• Errors are application/problem+json with a stable code to switch on (errors).
• Writes that create something take an Idempotency-Key: a retry never runs twice (idempotency).
• The API sends no CORS headers (except on its two public routes): call it from a server, never from a browser, so the key stays secret.
• Meta, TikTok and Snapchat numbers are read on each platform, in each ad account's currency and time zone: never add them up across platforms.

Pagination

Lists take limit (1 to 200, default 50) and cursor, and answer { data, has_more, next_cursor }. Pass next_cursor as it is to get the next page; it is null on the last one.

cursor=""
while :; do
  page=$(curl -s "https://api.apogee.ad/api/v1/ad-accounts?limit=200${cursor:+&cursor=$cursor}" \
    -H "Authorization: Bearer $APOGEE_API_KEY")
  echo "$page" | jq -r '.data[] | "\(.id) \(.name)"'
  cursor=$(echo "$page" | jq -r '.next_cursor // empty')
  [ -z "$cursor" ] && break
done

Versioning

/v1 only changes in ways that add: new routes, new optional fields, new error codes. Ignore what you do not know. A deprecation is announced with Deprecation and Sunset headers before anything is removed, and listed in the changelog.

Launching through the API

1. Creatives. Files on your machine: Create uploads (POST /uploads), a PUT of each file to its signed URL, then Confirm uploads (POST /uploads/confirm). A Frame.io, Dropbox or Google Drive link: Create import (POST /imports), then Get import (GET /imports/{id}). A Drive folder: List drive folder (GET /drive-folders). Each file gives a ref.
2. The interview. Get launch questions (POST /ad-accounts/{acc}/launch-questions) returns the questions the app asks, with the account's choices and a recommended answer.
3. The plan. Create launch plan (POST /launch-plans) with the answers: 422 missing_answers lists what is still open (nothing saved); 201 returns the recap and the plan id, valid 24 hours. Show the recap to the person who decides.
4. The launch. After their yes, Confirm launch plan (POST /launch-plans/{id}/confirm): 202 with the launch id. Then Get launch (GET /launches/{id}) until finished.

TikTok and Snapchat launch the same way, with platform in the questions and the plan. Changes (pause, budgets, duplicates…) follow the same pattern: Create action (POST /actions), then Confirm action (POST /actions/{id}/confirm) after the yes. So do Bridge transfers: Create bridge transfer (POST /bridge-transfers), then Confirm bridge transfer (POST /bridge-transfers/{id}/confirm).

All the operations

48 operations in 8 groups.