---
title: "Create a Rio Motion-agent job"
method: POST
path: "/sessions"
---

# Create a Rio Motion-agent job

`POST /sessions`

## Request body

- CreateMotionSessionRequest — Creates a durable Rio Motion-agent job owned by the API key user. Requires available Mosaic Motion credits on that user's account. Credits and auto top-ups are managed at https://motion.so, not through the API.
  - `prompt` string, required
  - `aspect_ratio` '16:9' | '9:16' | '1:1' | '4:5' | '21:9' — Target video aspect ratio.
  - `duration` '<10s' | '10-30s' | '30s-1min' | '1-5min' — Target video duration bucket.
  - `design_system_id` 'mosaic' | 'apple' | 'claude' | 'cursor' | 'linear' | 'vercel' | 'stripe' | 'figma' | 'notion' | 'spotify' | 'supabase' | 'raycast' | 'framer' | 'resend' | 'mintlify' | 'sentry' | 'tesla' | 'nike' | 'shopify' | 'airbnb' | 'posthog' — Pro/Max built-in DESIGN.md preset to apply.
  - `design_md` union — Pro/Max custom DESIGN.md content, optionally with a companion style extraction JSON artifact. If both design_system_id and design_md are sent, design_md content is used.
    - string
    - MotionDesignMd
      - `filename` string
      - `sourceUrl` string — Optional source website URL for imported style extraction context.
      - `content` string, required — Pro/Max markdown design system guidance saved as DESIGN.md for the job.
      - `jsonFilename` string — Optional companion style extraction JSON filename.
      - `jsonContent` string — Optional structured style extraction JSON saved alongside DESIGN.md for agent context.
  - `style_reference_url` string, uri — Optional YouTube style reference URL.
  - `attachments` MotionAttachment[]
    - `url` string, uri, required — Publicly accessible signed URL.
    - `name` string
    - `type` 'image' | 'video' | 'audio' | 'file'
    - `content_type` string

## Response `202`

Job accepted

- CreateMotionSessionResponse
  - `job_id` string, required
  - `status` 'queued', required
  - `status_url` string, uri, required — Authenticated public API polling URL for GET /sessions/{job_id}. This is not a Motion app page.
  - `chat_url` string, uri, nullable — Motion app chat URL for a human to open, inspect, or continue the run. Null only for legacy flows where no chat is available.

## Other responses

- `400` — Invalid request
- `401` — Missing or invalid Mosaic Motion API key
- `402` — Insufficient Mosaic Motion credits. Purchase credits or configure auto top-ups in the Motion frontend at https://motion.so.

---

[API](https://skmtc.dev/motion/apis/mosaic-motion.md) · [All operations](https://skmtc.dev/motion/apis/mosaic-motion/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/motion/mosaic-motion/revisions/15f372c6ad03/schema)