---
title: "Create a Tella Motion document"
method: POST
path: "/v1/motion/documents"
tags: ["Tella Motion"]
---

# Create a Tella Motion document

`POST /v1/motion/documents`

## Request

- Base URL: `https://api.tella.com`
- URL: `https://api.tella.com/v1/motion/documents`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/withchima/apis/tella-public-api/docs/v1/motion/documents/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a blank document, 10 s long (the `canvas.set` op changes that). With `videoId` it is the video's, as large as the video unless sized, for an overlay or b-roll you build in place. Without it the document is yours and in no video yet (1920×1080 unless sized); the first video it is placed in takes it over. Edit it with `POST /v1/motion/documents/{id}/commands`, then show it with `POST /v1/videos/{id}/clips/{clipId}/overlays` (`motionDocumentId`) or a layout's `media: {type: "motion", documentId}`. It plays there live, so later edits show in the video as you make them.

## Request body

- CreateMotionDocumentRequest: A blank document, owned by a video for an overlay or b-roll you build in place, or by you until a video takes it over. It is not put in the media library. Its canvas is 10 s long until a `canvas.set` op changes it.
  - `height` number: Canvas height in pixels. Defaults to the video's, or 1080 without a video.
  - `name` string, required: What it shows.
  - `videoId` string: The video (vid_…) that owns the document. Leave it out for one of your own that no video plays yet: the first video it is placed in takes it over.
  - `width` number: Canvas width in pixels. Defaults to the video's, or 1920 without a video.

## Response `201`

Created

- MotionDocumentResponse: A Tella Motion document
  - `document` MotionDocument, required: A Tella Motion document: a render timeline (a tree of media, sound, text, shape, sequence and composition nodes) that a Tella Motion clip, overlay or b-roll plays live, so edits show in the video at once.
    - `createdAt` string, required
    - `id` string, required: Document ID
    - `name` string, required
    - `ownerID` string, required: The owner's ID: the video's, for `story` documents; yours, for `user` documents.
    - `sceneID` string: The clip that plays this document, when it is a Tella Motion clip's. Absent for overlays and b-roll.
    - `scope` string, required: Who owns the document: `story` for a video's own documents (its Tella Motion clips, overlays and b-roll), `user` for one of yours that no video plays yet.

## Other responses

- `400`: The request was malformed or contained invalid parameters.
- `401`: Authentication is required. Provide a valid API key.
- `403`: You don't have permission to access this resource.
- `404`: The requested resource was not found.
- `409`: The request conflicts with the resource's current state, e.g. an Idempotency-Key whose first request is still in progress. Retry once it settles.
- `429`: You have exceeded the rate limit. Please slow down.
- `500`: An unexpected error occurred
- `501`: The requested operation is not implemented.
- `503`: A dependency was unavailable and the request was not executed. Safe to resend unchanged after the Retry-After delay.

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-27** `240a74ea0ff7`: 1 info
  - the request property `videoId` became optional
- **2026-10-22** `156b28c30e54`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/withchima/apis/tella-public-api/changes/v1/motion/documents/post.md)

---

[API](https://skmtc.dev/withchima/apis/tella-public-api.md) - [All operations](https://skmtc.dev/withchima/apis/tella-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/withchima/apis/tella-public-api/revisions/0cc3fcd307ad?raw)