Endpoint reference

Base URL: your backend origin + /api. On the hosted deployment that is https://motion-back-production.up.railway.app/api.

Conventions

In the Credential column, session means a signed-in JWT only; key means an API key with the named scope, and a session JWT also works.

API keys

Create body

{
  "name": "n8n production",
  "scopes": ["renders:read", "renders:write", "templates:read", "usage:read"],
  "expiresAt": "2027-08-27T00:00:00.000Z"
}

name defaults to "API key" and is truncated to 80 characters. scopes defaults to the four above. expiresAt must be in the future, or omitted.

ApiKeySummary

{
  id: string
  name: string
  prefix: string            // "pm_live_ab12cd" — not the secret
  scopes: string[]
  createdAt: string
  lastUsedAt: string | null
  requestCount: number
  expiresAt: string | null
  revokedAt: string | null
}

The create response adds secret: string, returned once and never again.

Templates

Import takes multipart/form-data, not JSON:

Inputs are derived from layer names, and a layer whose source is local becomes required. See Automating a project you already have.

Template

{
  id: string
  name: string
  description: string | null
  width: number
  height: number
  fps: number
  durationSeconds: number
  inputs: TemplateInput[]
  createdAt: string
  updatedAt: string
}

TemplateInput

{
  id: string                                        // /^[a-z][a-zA-Z0-9]{0,63}$/
  label: string
  kind: 'text' | 'color' | 'number' | 'image' | 'media'
  required?: boolean                                // defaults true for image/media
}

Publish body — name, document, inputs, width, height, fps, durationSeconds required; description and projectId optional. See Templates & inputs.

Renders

Create body

{
  templateId: string
  inputs: Record<string, string | number>
  output?: {
    format?: 'mp4'
    width?: number     // 64–4096
    height?: number    // 64–4096, w × h ≤ 16 MP
    fps?: number       // 1–120
  }
  callbackUrl?: string // public http(s) only
}

Optional header: Idempotency-Key, 8–128 characters from A-Z a-z 0-9 . _ : -.

Job

{
  jobId: string
  status: 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled'
  progress: number
  videoUrl: string | null
  error: string | null
  createdAt: string
}

Assets

Upload bytes, get a URL a render can read. The route that removes S3 from the middle of a workflow.

multipart/form-data with the file in a file field.

{
  url: string        // pass straight into a render's `inputs`
  bytes: number
  mime: string       // determined from the bytes, not from what you declared
  expiresAt: string  // 24 hours out
}

Accepted: PNG, JPEG, WebP, GIF, SVG, MP4, WebM, QuickTime, MP3, WAV, M4A. Size is capped by your plan’s maxUploadBytes; over it is 413 naming the limit. A declared type that contradicts the actual bytes is 400 — but a generic application/octet-stream is read as “no type given” and the bytes decide.

Usage

Shape in Plans, quotas & limits.

Animation presets

The cloud-synced preset library. Not video templates — see the note.

POST upserts on name: publishing the same name again replaces the data and increments version rather than creating a second row.

{ "name": "Bouncy fade in", "animationData": { "…": "preset payload" } }

Webhook delivery

Not an endpoint you call — one Premation sends. POST to your callbackUrl, once per terminal transition.

{
  jobId: string
  status: 'completed' | 'failed' | 'cancelled'
  videoUrl: string | null
  error: string | null
  renderDurationMs: number | null
}

Unsigned. Confirm with GET /v1/renders/{id} before acting — see Webhooks.

Not public

Everything outside /v1 — /auth, /projects, /assets, /ai, /sync, /files, /billing, /plugins, /admin — backs the editor, the dashboard and the operator console. Those routes are session-authenticated, change without notice, and reject pm_live_ keys. Do not build on them.