Templates

Store movie documents as reusable templates with declared `{{variables}}`, then render them with per-request values — the data-driven video workflow.

Store movie documents as reusable templates with declared {{variables}}, then render them with per-request values — the data-driven video workflow.

All endpoints live under https://api.automotion.dev/v1, require Authorization: Bearer <api key>, and answer with the standard envelopes.

POST `/templates`

Create a template. Store a movie document as a reusable template. The document's declared variables (body.variables) become the template's manifest; declared-but-unused variables are returned as warnings.

Request body

The template to create.

Field	Type	Default	Description
`name` *	string (non-empty)	—	Display name of the template.
`body` *	object	—	The template's movie document, with {{variable}} placeholders. Its declared variables (body.variables) become the template's manifest.

Example

curl -X POST https://api.automotion.dev/v1/templates \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily update",
    "body": {
      "schema": "v1",
      "preset": "9:16",
      "variables": {
        "headline": {
          "type": "string",
          "description": "Today's headline."
        }
      },
      "scenes": [
        {
          "id": "update",
          "duration": 4,
          "background": "#1e293b",
          "elements": [
            {
              "id": "update-text",
              "type": "text",
              "text": "{{headline}}"
            }
          ]
        }
      ]
    }
  }'

Responses

201 — The created template, with manifest warnings. Returns TemplateWriteResource.

`TemplateWriteResource`

Field	Type	Default	Description
`id` *	string (non-empty)	—	Template id.
`name` *	string (non-empty)	—	Display name of the template.
`body` *	object	—	The template's movie document, verbatim as stored, with {{variable}} placeholders.
`variables` *	object	—	The declared variables manifest (mirrors body.variables; empty object when none).
`createdAt` *	string (date-time)	—	Creation time (ISO-8601).
`updatedAt` *	string (date-time)	—	Last update time (ISO-8601).
`warnings` *	object[]	—	Non-fatal manifest findings (e.g. declared-but-unused variables). Never stored.

Errors

VALIDATION_ERROR · SCHEMA_INVALID · UNSUPPORTED_SCHEMA_VERSION · ELEMENT_ID_DUPLICATE · SCENE_ID_DUPLICATE · SCENE_EMPTY · VARIABLE_UNDECLARED — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

GET `/templates`

List templates. List the caller's templates, newest first, with page pagination.

Parameters

Name	In	Type	Required	Description
`page`	query	integer (≥ 1)	no	1-based page number.
`page_size`	query	integer (1–100)	no	Page size (max 100).

Example

curl https://api.automotion.dev/v1/templates \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

200 — A page of templates. Returns TemplateListResource.

`TemplateListResource`

Field	Type	Default	Description
`items` *	object[]	—	The page of results, newest first.
`page` *	integer (≥ 1)	—	1-based page number.
`pageSize` *	integer (≥ 1)	—	Number of items per page.
`total` *	integer (≥ 0)	—	Total number of matching items.
`hasMore` *	boolean	—	Whether further pages exist (page * pageSize < total).

Errors

VALIDATION_ERROR — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

GET `/templates/{id}`

Get a template. Fetch a template with its document and variables manifest.

Parameters

Name	In	Type	Required	Description
`id`	path	string (non-empty)	yes	The template id.

Example

curl https://api.automotion.dev/v1/templates/$TEMPLATE_ID \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

200 — The template. Returns TemplateResource.

`TemplateResource`

Field	Type	Default	Description
`id` *	string (non-empty)	—	Template id.
`name` *	string (non-empty)	—	Display name of the template.
`body` *	object	—	The template's movie document, verbatim as stored, with {{variable}} placeholders.
`variables` *	object	—	The declared variables manifest (mirrors body.variables; empty object when none).
`createdAt` *	string (date-time)	—	Creation time (ISO-8601).
`updatedAt` *	string (date-time)	—	Last update time (ISO-8601).

Errors

NOT_FOUND — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

PUT `/templates/{id}`

Update a template. Replace a template's name and/or document (re-validated).

Parameters

Name	In	Type	Required	Description
`id`	path	string (non-empty)	yes	The template id.

Request body

The fields to replace (at least one).

Field	Type	Default	Description
`name`	string (non-empty)	—	New display name.
`body`	object	—	An Automotion movie document. The "schema" tag selects the Movie Schema version it is parsed under.

Example

curl -X PUT https://api.automotion.dev/v1/templates/$TEMPLATE_ID \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily update (v2)"
  }'

Responses

200 — The updated template, with manifest warnings. Returns TemplateWriteResource.

`TemplateWriteResource`

Field	Type	Default	Description
`id` *	string (non-empty)	—	Template id.
`name` *	string (non-empty)	—	Display name of the template.
`body` *	object	—	The template's movie document, verbatim as stored, with {{variable}} placeholders.
`variables` *	object	—	The declared variables manifest (mirrors body.variables; empty object when none).
`createdAt` *	string (date-time)	—	Creation time (ISO-8601).
`updatedAt` *	string (date-time)	—	Last update time (ISO-8601).
`warnings` *	object[]	—	Non-fatal manifest findings (e.g. declared-but-unused variables). Never stored.

Errors

VALIDATION_ERROR · SCHEMA_INVALID · UNSUPPORTED_SCHEMA_VERSION · ELEMENT_ID_DUPLICATE · SCENE_ID_DUPLICATE · SCENE_EMPTY · VARIABLE_UNDECLARED · NOT_FOUND — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

DELETE `/templates/{id}`

Delete a template. Delete a template. Renders already created from it are unaffected.

Parameters

Name	In	Type	Required	Description
`id`	path	string (non-empty)	yes	The template id.

Example

curl -X DELETE https://api.automotion.dev/v1/templates/$TEMPLATE_ID \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY"

Responses

204 — Deleted.

Name	In	Type	Required	Description
`id`	path	string (non-empty)	yes	The template id.
`Idempotency-Key`	header	string (non-empty, ≤ 255 chars)	no	Optional client-chosen key making the create retry-safe (§9): replaying the same key with the same body returns the ORIGINAL render with 200; a different body is rejected with IDEMPOTENCY_KEY_REUSED.

Request body

Variable values and render options.

Field	Type	Default	Description
`variables`	object	—	Values for the declared variables, keyed by variable name.
`webhook_url`	string (uri)	—	Webhook notified on render.completed / render.failed. Paid plans only; trial requests are rejected with WEBHOOKS_NOT_ALLOWED.
`draft`	boolean	—	Render a fast, low-resolution, watermarked draft instead of the final output.

Example

curl -X POST https://api.automotion.dev/v1/templates/$TEMPLATE_ID/renders \
  -H "Authorization: Bearer $AUTOMOTION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "variables": {
      "headline": "Automotion ships the docs"
    }
  }'

Responses

201 — The queued render. Returns RenderResource.
200 — Idempotent replay: the same Idempotency-Key with the same body returns the original render. Returns RenderResource.

`RenderResource`

Field	Type	Default	Description
`id` *	string (non-empty)	—	Render id.
`status` *	"queued" \| "preparing" \| "rendering" \| "done" \| "failed"	—	Render lifecycle state (§6): queued → preparing → rendering → done \| failed.
`progress` *	integer (0–100)	—	Monotonic progress percent: 0–20 preparing, 20–99 rendering, 100 done.
`draft` *	boolean	—	Whether this is a fast low-res draft render.
`watermark` *	boolean	—	Whether the output carries the Automotion watermark (drafts and the trial plan).
`outputUrl` *	string (uri) \| null	—	CDN URL of the finished MP4. Null until the render is done.
`expiresAt` *	string (date-time) \| null	—	When the output expires per the plan's retention window (30d trial / 90d Starter+Pro / 365d Studio). Set on completion.
`error` *	object \| null	—	The failure, when status is failed. Always references a catalog code. Null otherwise.
`durationSec` *	number (≥ 0) \| null	—	Output duration in seconds, known once preparation finishes.
`meteredMinutes` *	number (≥ 0) \| null	—	Weighted render minutes charged against the credit balance (10 credits each), set when the render completes.
`fps` *	integer (> 0)	—	Frames per second of the output.
`templateId` *	string (non-empty) \| null	—	Source template id when the render was created from a template.
`webhookUrl` *	string (uri) \| null	—	Webhook target notified on completion or failure (paid plans).
`createdAt` *	string (date-time)	—	Creation time (ISO-8601).
`updatedAt` *	string (date-time)	—	Last state-change time (ISO-8601).

Errors

NOT_FOUND · VALIDATION_ERROR · SCHEMA_INVALID · UNSUPPORTED_SCHEMA_VERSION · ELEMENT_ID_DUPLICATE · SCENE_ID_DUPLICATE · SCENE_EMPTY · VARIABLE_MISSING · VARIABLE_TYPE_MISMATCH · VARIABLE_UNDECLARED · INSUFFICIENT_CREDITS · CONCURRENCY_LIMIT · IDEMPOTENCY_KEY_REUSED · WEBHOOKS_NOT_ALLOWED — plus the pipeline-wide UNAUTHORIZED · RATE_LIMITED · INTERNAL.

POST `/templates`

Request body

Example

Responses

`TemplateWriteResource`

Errors

GET `/templates`

Parameters

Example

Responses

`TemplateListResource`

Errors

GET `/templates/{id}`

Parameters

Example

Responses

`TemplateResource`

Errors

PUT `/templates/{id}`

Parameters

Request body

Example

Responses

`TemplateWriteResource`

Errors

DELETE `/templates/{id}`

Parameters

Example

Responses

Errors

POST `/templates/{id}/renders`

Parameters

Request body

Example

Responses

`RenderResource`

Errors

On this page