Skip to main content
POST
Create a project

Authorizations

Authorization
string
header
required

A Motion API key. Access is limited to its stored organization, workspace, scopes and the creator’s current permissions.

Scopes

motion:sessions:write

Create and steer Motion projects using organization workspace credits.

Headers

Idempotency-Key
string<uuid>

Optional UUID for identical REST retries. Reuse the same key and body after a lost response.

Body

application/json
prompt
string
required

Describe the work to do. Include source links, size, duration, layout and style in the prompt.

Required string length: 1 - 12000
effort
enum<string>

Project effort, fixed at creation: standard or extended. Defaults to standard. Follow-up messages and resumed turns keep this choice.

Available options:
standard,
extended
attachments
object[]

Uploaded library assets only. Put web links directly in prompt text.

Maximum array length: 100
template_ids
string[]

Saved template IDs from List templates to attach with this message. Earlier references remain in conversation history.

Maximum array length: 8
Pattern: ^[a-zA-Z0-9_-]{1,160}$
brand_kit_ids
string<uuid>[]

Saved brand-kit UUIDs from List brand kits. Omit to inherit the current selection; an array replaces it and [] clears it.

Maximum array length: 8
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
connectors
object[]

Exact connections the agent may use, at most one per provider. Omit to keep the project's selection; an array replaces it for this and later turns, including the following tool calls of an active turn; [] disables all connectors. Selecting connections needs motion:connectors:read for your private connections in this organization workspace.

Maximum array length: 18
export_formats
enum<string>[]

Automatically export the finished outputs in these formats. You can also request exports later.

Maximum array length: 10
Available options:
mp4,
png,
jpeg,
media,
premiere,
after-effects,
resolve,
final-cut,
psd,
svg

Response

Success

project_id
string<uuid>
required

Motion project chat UUID returned by create_project or list_projects.

message_id
string<uuid>
required

Durable user-message UUID accepted for this request.

turn_id
string<uuid> | null
required

Starting user-message UUID shared by all messages and saved generations from one turn. Steering retains this ID; historical turns may have no recorded ID.

chat_url
string<uri>
required

Motion web chat URL where the user can inspect and continue this project.

status
enum<string>
required

Project work status. Completed means the agent finished; exports may still be preparing.

Available options:
queued,
running,
completed,
failed,
cancelled,
awaiting_user_input,
awaiting_credits