REST API Guide

This guide covers the cross-cutting conventions of the headless REST API: base URLs, authentication, the response envelope, the asset upload flow, and the asynchronous polling pattern.

For the full per-endpoint reference — every request/response schema and field type — see the Interactive API Reference. It renders only the endpoints a headless API key may call. The raw headless.yaml spec is also downloadable; load it into Postman/Insomnia for a live "try it" console.

Base URLs

Environment	Base URL
Production	https://api.nativeads.ai/v1
Staging	https://staging-api.nativeads.ai/v1
Development	https://dev-api.nativeads.ai/v1

Authentication

Send your API key as a bearer token on every request:

Authorization: Bearer nak_<env>_<keyId>.<secret>

A key acts as its owning user and is confined to the developer surface. Any other /v1 route returns 403. See Get an API key.

Response format

The success envelope is not uniform — read the shape per endpoint in the API Reference:

• { status, data } wrapper: brand-DNA versions, legacy brand-DNA read, feature usage.
• Bare resource object: brands, assets, scene forges, prompt enhancements, generated video groups.
• List wrapper { data: [...], pagination: {...} }: brand list, scene-forge list, video-group list. Brand assets use a category-grouped shape ({ categories: [...] }).

Errors are always:

{
  "requestId": "…",
  "error": { "code": "…", "message": "…", "details": {} }
}

Optimistic concurrency: brand updates use ETag / If-Match; brand-DNA version updates use an updatedAt token in the body.

Asset upload flow

Uploads are a three-step presign → client-PUT → confirm flow. The API never receives file bytes directly.

1. POST /assets/initiate-upload — declare the files (fileName, fileType, fileSize ≤ 500 MB, dimension). Returns a presigned uploadUrl + uploadId per file.
2. PUT the raw bytes to uploadUrl (a presigned S3 URL) before it expires. Not a backend call.
3. POST /assets/confirm-upload with the uploadId. Starts async processing; poll GET /assets/{assetId} until status is complete.

Allowed fileType values: image/jpeg, image/png, image/svg+xml, image/tiff, video/mp4, video/quicktime, application/pdf.

Asynchronous operations

Every generation and Brand-DNA extraction is fire-and-poll. There is no /tasks endpoint: each asynchronous create returns a resource id, and you poll that resource's GET-by-id endpoint until it reaches a terminal status.

Create call	Poll endpoint	Terminal statuses
POST /brands/{brandId}/scene-forges	GET /scene-forges/{id}	completed / failed
POST /brands/{brandId}/generate-video	GET /generated-videos-groups/{id}	completed / failed
POST /brands/{brandId}/scene-forge-prompt-enhancements	GET /brands/{brandId}/scene-forge-prompt-enhancements/{id}	completed / failed
POST /brands/{brandId}/image-to-video-prompt-enhancements	GET /brands/{brandId}/image-to-video-prompt-enhancements/{id}	completed / failed
POST /brands/{brandId}/brand-dna/versions (or /rerun)	GET /brands/{brandId}/brand-dna/versions/{versionId}	ready / failed

Example: submit a Scene Forge job and poll until it finishes.

# 1. Submit — returns an id
ID=$(curl -s -X POST "https://api.nativeads.ai/v1/brands/$BRAND_ID/scene-forges" \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"blendingPrompt":"product on a marble kitchen counter","promptIsEnhanced":false,"useBrandDna":true}' \
  | jq -r '.sceneForgeId')

# 2. Poll until terminal
while true; do
  STATUS=$(curl -s "https://api.nativeads.ai/v1/scene-forges/$ID" \
    -H "Authorization: Bearer $NATIVEADS_API_KEY" | jq -r '.status')
  echo "status: $STATUS"
  case "$STATUS" in
    completed) echo "done"; break ;;
    failed)    echo "generation failed"; exit 1 ;;
    *)         sleep 3 ;;
  esac
done

Use a bounded number of attempts and a backoff in production. Brand-DNA versions use ready instead of completed as their success status.

If you integrate over MCP instead, the get_task tool wraps this polling behind a single task id.

Endpoints not available to keys

For security, an API key is confined to the developer surface. Notably not available to keys: brand deletion, asset deletion, API-key management, campaign/theme generation, trends, and Walmart-creative submission. These remain available to human users in the app.