> ## Documentation Index
> Fetch the complete documentation index at: https://docs.motion.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects and exports

> Create projects, continue work and download finished files.

## Create and continue

Create a project with `POST /projects`. Send more work with `POST /projects/{id}/messages`, including while the agent is working. Stop it with `POST /projects/{id}/stop`; send another message to continue.

```json theme={null}
{
  "prompt": "Create a launch video and two thumbnails.",
  "effort": "standard",
  "export_formats": ["mp4", "png"]
}
```

`effort` is `standard` or `extended`, chosen at creation and fixed for the project. Follow-up messages accept the same creative inputs without `effort`.

Attach uploaded library files through `attachments: [{"asset_id": "ASSET_UUID"}]`. Put web links directly in the prompt. Add saved references with `template_ids` and `brand_kit_ids`. Choose connections with `connectors: [{"id": "CONNECTION_UUID", "actions": ["pages"]}]`; action IDs come from List connectors. All selections must be accessible to your credential.

## Read the project

`GET /projects/{id}` returns:

| Field | Meaning |
| - | - |
| `status` | Current work status. |
| `messages` | Conversation messages and user-visible progress explanations. |
| `generations` | Saved project versions. Each contains its editable `compositions`. |
| `exports` | Export status, format and download links. Includes exports requested in the app. |
| `export_formats` | Current automatic export settings for future turns. |

One generation can contain a video and two thumbnails: these are three compositions in one saved version. Use the composition's `id` when exporting; use the generation's `id` when saving the whole version as a template.

Messages, generations and exports share `turn_id`, so you can match work to the turn that produced it. A steering message belongs to the active turn. A later follow-up starts another turn. Historical records may have no recorded turn ID.

`limit` sets the page size for both messages and generations. Use `after_sequence` for more messages and `cursor` for more generations. Use the export cursor with List exports.

## Automatic exports

Set `export_formats` to automatically export finished compositions when each turn finishes. For example, `["mp4", "png"]` exports videos as MP4 and images as PNG.

Follow-up messages inherit the formats. Send a new array to change them, or `[]` to turn automatic exports off. Turns that only answer a question have nothing to export. An explicit request that cannot produce the requested format returns a failed export.

A completed project can have no exports when none were requested. Exports may still be preparing after the agent finishes.

## Export later

Use `POST /projects/{id}/exports` at any time after a composition is saved:

```json theme={null}
{
  "composition_ids": ["GENERATION_UUID:film"],
  "format": "mp4"
}
```

Copy composition IDs from Read a project. Treat them as opaque IDs; do not construct them yourself. You can select several compositions, including older versions of the same project. Each receives a separate export ID.

| Composition | Formats |
| - | - |
| Video | `mp4`, `premiere`, `after-effects`, `resolve`, `final-cut` |
| Image | `png`, `jpeg`, `psd`, `svg` |
| Either | `media` |

`media` exports a video as MP4 or an image as PNG. Editor exports include the project and its required assets.

| Format | Delivered content |
| - | - |
| `mp4`, `png`, `jpeg`, `psd`, `svg` | The named file type |
| `media` | MP4 for videos; PNG for images |
| `premiere` | Premiere `.prproj` project |
| `after-effects` | After Effects `.aep` project |
| `resolve` | Resolve import package with an OTIO timeline |
| `final-cut` | Final Cut `.fcpbundle` library |

A download can be a file or a ZIP containing those files. Check `filename` and `content_type`; `format` identifies the requested export type.

## Download files

Read exports inside Read a project, through `GET /projects/{id}/exports`, or individually with `GET /projects/{id}/exports/{export_id}`. All three return the same export objects.

Each includes `composition_ids`, `generation_id`, `turn_id`, `format`, `status`, and `download_url`. Status is `preparing`, `completed`, or `failed`. A download link is available after completion and expires after one hour; read again to renew it.

`stage: waiting` means dispatch has not started. Poll until the export is completed or failed.

`created_by_you` tells you whether your user requested the export. `origin` is `api` or `app`. Later edits and other people's exports do not change your export's saved source. Older app bundles may contain several compositions or have no recorded generation link.

## Access

API keys are bound to an organization and workspace. Scopes and your current permissions both apply. Project writes require `motion:sessions:write`; reads require `motion:sessions:read`. Selecting templates, brand kits, assets or connectors also requires their read scopes. Editor exports require Pro or above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.