REST API · Creatives

Create import

Import the creatives behind a link into Apogee storage

POSThttps://api.apogee.ad/api/v1/imports

Scope: launch Pro and Scale plans Credits: Free* Idempotency-Key required

What it does

Frame.io (project, folder or file; a public share link works without a Frame.io account, 20 to 30 s to read), Dropbox (shared file or folder) or Google Drive (file or folder; Frame.io / Drive / Dropbox accounts are the ones connected in the app). Answers 202 with an import id: follow it with GET /imports/{id} until done. The first 200 files of a link at most, counted in the day's upload budget (429 rate_limited past it).

Request

POST /imports on https://api.apogee.ad/api/v1.

Headers

Authorization string header required

Bearer apk_…: an API key with the scope of this route.
Idempotency-Key string header required

A unique key per request, e.g. a UUID, reused when you retry it: the first answer comes back instead of a second write (idempotency).

1 to 255 visible ASCII characters
Content-Type string header required

application/json

Body

url string (uri) required

The link

up to 2,048 characters

Response

202.

id string
source string

One of frameio, google_drive, dropbox
jobs array of objects
Fields of each item (7)
- id string
- name string or null
- status string
  
  One of PENDING, PROCESSING, COMPLETED, FAILED, MISSING
- progress number or null
- size_bytes number or null
- ref string or null
- error string or null
share_name string or null
done boolean
created_at string or null
note string

Why an import has no file (done at once)
truncated boolean
skipped_too_large array of values

Every answer carries X-Request-Id (give it to support), Apogee-Version: 2026-10-06, and the RateLimit and RateLimit-Policy headers; a replayed answer also carries Idempotent-Replayed: true.

Errors

Errors are application/problem+json with a stable code to switch on (all the codes).

Status	Possible codes
400 Bad request	`idempotency_key_required`, `not_supported`, `request_refused`, `validation_failed`
401 Unauthorized	`invalid_api_key`
403 Forbidden	`account_not_connected`, `forbidden`, `insufficient_scope`, `meta_permission_denied`, `platform_permission_denied`, `upgrade_required`
404 Not found	`not_found`
409 Conflict	`action_already_ran`, `idempotency_in_progress`, `plan_already_launched`
422 Unprocessable content	`budget_above_cap`, `idempotency_key_reused`, `launch_refused`, `missing_answers`
429 Too many requests	`daily_read_cap`, `meta_rate_limited`, `platform_rate_limited`, `quota_exceeded`, `rate_limited`
500 Internal server error	`internal_error`

Example

With your key in APOGEE_API_KEY (create one):

Request

curl -X POST 'https://api.apogee.ad/api/v1/imports' \
  -H "Authorization: Bearer $APOGEE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://www.dropbox.com/scl/fo/example0000/nordlicht-creatives"
}'

Response 202 (shape)

{
  "id": "120200000000000001",
  "source": "frameio",
  "share_name": "Nordlicht | Spring launch",
  "done": false,
  "created_at": "2026-10-23T09:00:00.000Z",
  "note": "Example text",
  "jobs": [
    {
      "id": "120200000000000001",
      "name": "Nordlicht | Spring launch",
      "status": "PENDING",
      "progress": 100,
      "size_bytes": 48213112,
      "ref": "120200000000000001",
      "error": "120200000000000001"
    }
  ],
  "truncated": false,
  "skipped_too_large": [
    "120200000000000001"
  ]
}

Access and cost

Plans	Pro and Scale.
Scope	`launch` (scopes).
Credits	Free up to the daily free reads (5,000 a day on Pro, 10,000 on Scale), then 1 credit per read. A request that fails costs nothing, a replayed one neither (credits).
Rate limit	Write: 120 per 15 minutes on Pro, 240 on Scale (rate limits).
Daily cap	Counts 2 units toward the 2,000 units one API key can use in 24 hours.

In the MCP

An AI assistant does the same with this tool of the MCP server:

import_link: Imports the creatives behind a Frame.io, Dropbox or Google Drive link (a file or a folder) through the account connected to Apogee. A public Frame.io share works without a Frame.io account when downloads are allowed; a password-protected share does not.

Get import: GET /imports/{id}
List drive folder: GET /drive-folders
Create uploads: POST /uploads
Confirm uploads: POST /uploads/confirm
List TikTok posts: GET /ad-accounts/{acc}/tiktok-posts
List TikTok music: GET /ad-accounts/{acc}/tiktok-music
List platform templates: GET /ad-accounts/{acc}/platform-templates

What it does

Request

Headers

Body

Response

Errors

Example

Access and cost

In the MCP

Related operations