Skip to main content

Developer Quickstart

The NativeAds headless platform lets you drive the full creative-generation pipeline programmatically: create and manage brands, extract Brand DNA, upload assets, and generate images and video. Two integration paths are available and share the same authentication and permission model:

  • REST API — call the HTTP endpoints directly from any language. See the REST API Guide.
  • MCP server — connect an AI agent or MCP client (Claude, Cursor, ChatGPT, and others) to the same capabilities as tools. See Connect via MCP.

This page gets you authenticated and making your first call.

1. Get an API key​

API keys are the credential for headless access. Any user issues their own key from the NativeAds dashboard. Keys have the form:

nak_<env>_<keyId>.<secret>

Key properties:

  • Shown once. The full token (including the secret) is displayed only at creation time. Store it in a secret manager immediately, it cannot be retrieved again.
  • Per user, mirrors your role. A key acts as its owning user within that user's organization. It carries the owner's live role, so it can do exactly what the owner can do, no more. If the owner's role changes or they are removed from the organization, the key's access changes with it on the next request.
  • Never expires unless you set an expiry. Keys are valid until deleted. An optional expiry can be set at creation. Deleting a key takes effect on its next use.
  • Regenerate to rotate. Regenerating a key issues a fresh token for the same key (same name); the old token stops working immediately.

Treat a key like a password. Anyone holding it can act as its owner.

2. Authenticate a REST call​

Send the key as a bearer token on every request:

curl https://api.nativeads.ai/v1/brands \
  -H "Authorization: Bearer nak_production_<keyId>.<secret>"

Environments:

EnvironmentREST base URLMCP endpoint
Productionhttps://api.nativeads.ai/v1https://mcp.nativeads.ai/mcp
Staginghttps://staging-api.nativeads.ai/v1https://staging-mcp.nativeads.ai/mcp
Developmenthttps://dev-api.nativeads.ai/v1https://dev-mcp.nativeads.ai/mcp

Use a key minted for the matching environment (the <env> segment is a routing hint).

An invalid, unknown, revoked, or expired key returns 401. A valid key that calls an endpoint outside the permitted developer surface returns 403.

3. Make your first request​

List the brands in your organization:

curl https://api.nativeads.ai/v1/brands \
  -H "Authorization: Bearer $NATIVEADS_API_KEY"

Create a brand:

curl -X POST https://api.nativeads.ai/v1/brands \
  -H "Authorization: Bearer $NATIVEADS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Coffee",
    "industry": "Food & Beverage",
    "description": "Small-batch specialty coffee roasted daily.",
    "mission": "Make exceptional coffee accessible to everyone.",
    "values": ["Quality", "Sustainability"],
    "tone": ["Friendly", "Authoritative"],
    "voice": ["Warm", "Knowledgeable"]
  }'

Generate your first image​

Listing brands proves auth works. To see the platform actually produce a creative, the shortest path is:

  1. Create a brand (above) and note its id.
  2. Add Brand DNA from your website and activate it — POST /brands/{brandId}/brand-dna/versions with { "urls": ["https://your-site.com"] }, poll the version until status: ready, then POST …/activate.
  3. Generate a Scene Forge image — POST /brands/{brandId}/scene-forges with a blendingPrompt and useBrandDna: true. This returns 202 with an id.
  4. Poll GET /scene-forges/{id} until status: completed; the variations[] carry the generated image assets.

The full copy-paste walkthrough is in Recipes → Generate a product image.

Response format​

Responses are JSON. The envelope is not uniform across the API, so read the reference for the shape of each endpoint:

  • Some endpoints (brand-DNA versions, feature usage) wrap the payload as { "status": ..., "data": ... }.
  • Others (brands, assets, scene forges, video groups) return the resource object directly.
  • List endpoints return { "data": [...], "pagination": {...} } (or a category-grouped shape for brand assets).

Errors always use the same shape:

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

Asynchronous operations​

Every generation and extraction operation is fire-and-poll. The create call returns quickly with a resource id and a pending/processing status; you then poll that resource until it reaches a terminal state (completed, ready, or failed). Over MCP, the get_task tool wraps this polling. See Asynchronous operations for the full mapping.

Next steps​

Questions? Contact support@nativeads.ai.