API overview

The Automotion API is a small REST surface under a single base URL:

https://api.automotion.dev/v1

Requests and responses are JSON (camelCase fields, ISO-8601 dates, explicit nulls). The full surface is described by an OpenAPI 3.1 document generated from the same schemas the server validates with — the endpoint pages (Renders, Templates, Assets, Usage) are generated from it, so they cannot drift from behavior.

Authentication

Every request carries an API key as a bearer token:

curl https://api.automotion.dev/v1/usage \
  -H "Authorization: Bearer am_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

• Keys look like am_live_… or am_test_… (40 random characters) and are created in the dashboard. The secret is shown once; only a hash is stored.
• Any authentication failure — missing header, malformed, unknown or revoked key — answers the identical UNAUTHORIZED envelope. Responses never reveal whether a key exists.
• Rolling a key creates the replacement before revoking the old one, so a failed roll never leaves you keyless.

Idempotency

Render-creating endpoints (POST /renders, POST /templates/{id}/renders) accept an Idempotency-Key header:

• Same key + same body within 24 h → the original render is returned with 200 (no new render is created).
• Same key + different body → IDEMPOTENCY_KEY_REUSED (409).
• A request that fails stores nothing — retrying with the same key is safe.

Use a deterministic key per logical unit of work (order-1234-v1) and retries — network blips, worker restarts, replayed queue messages — can never double-render.

Rate limits

Requests are rate-limited per API key over a sliding window:

Every authenticated response carries the current window state:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 12
X-RateLimit-Reset: 1789000000

X-RateLimit-Reset is epoch seconds. Exceeding the limit answers 429 RATE_LIMITED; back off until the reset time. Separate from request rates, your credit balance funds all consumption (10 credits per render minute, 1 credit per AI image generation) and is enforced at render creation together with the concurrency cap — see INSUFFICIENT_CREDITS and CONCURRENCY_LIMIT, and check GET /v1/usage for your live balance.

Pagination

List endpoints (GET /renders, GET /templates) take page (1-based) and page_size (≤ 100, default 20) and answer a uniform envelope:

{
  "items": [],
  "page": 1,
  "pageSize": 20,
  "total": 137,
  "hasMore": true
}

Ordering is newest-first and stable (createdAt desc, id desc). GET /renders additionally filters by status, created_after and created_before (inclusive ISO-8601 bounds).

Variables

Movie documents may declare typed {{variables}} and reference them in any string value; renders resolve them from the request's variables object, falling back to declared defaults. The rules (declaration, lossless coercion, escaping literal braces with {{{{name}}}}) are covered in the data-driven guide and the movie settings reference.

Errors

Every non-2xx response is the same envelope:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Opacity must be between 0 and 1.",
    "path": "scenes[0].elements[1].opacity",
    "docsUrl": "https://automotion.dev/docs/errors/validation_error"
  },
  "requestId": "req_0123456789abcdef0123456789abcdef"
}

• code is stable and machine-matchable — every code is documented in the error catalog, and docsUrl links straight there.
• path (present when applicable) is the exact JSON path of the offending field, e.g. scenes[2].elements[0].src.
• requestId also arrives as the X-Request-Id response header — include it in support requests.
• Document validation returns everything at once: an additional errors array lists ALL findings (error is always errors[0]), so one request surfaces every problem in the document.

The HTTP status is determined by the code (400 validation, 401 auth, 402 credits, 404 not found, 409 idempotency conflict, 422 asset problems, 429 rate limiting, 5xx platform faults). A failed render carries the same error shape in its error field.

Drafts, watermarks and retention

• "draft": true in the movie renders fast, low-res, watermarked, at half the credit cost — iterate on drafts, finalize without.
• Trial renders are always watermarked.
• Outputs expire (expiresAt on the render): 30 days on Trial, 90 days on Starter and Pro, 365 days on Studio. Copy the MP4 to your own storage if you need it longer.

OpenAPI document

The machine-readable OpenAPI 3.1 description (the source of these reference pages and of the TypeScript SDK) ships with the schema package as @automotion/schema/openapi.json.