# Motion Reel docs. Connect an agent, or call the API.

> One set of operations does everything: schedule a reel, set up comment-to-DM, answer comments, read the numbers. An AI agent calls them as MCP tools, and your own code calls them over HTTP.

Motion Reel (https://motionreel.app). The page: https://motionreel.app/docs. Updated November 17, 2026.

## Before the first call

- **An account:** A Motion Reel account on a trial or a plan: 7 days free, with a card to start. The MCP server and the API are on every plan. https://motionreel.app/pricing
- **Connected accounts:** Connect your Instagram accounts and YouTube channels in the dashboard, each with the platform's own login. An agent or a key can't connect one.

## The MCP server

For Claude, Codex, Cursor and any other MCP client.

- **Address:** https://motionreel.app/mcp, over Streamable HTTP.
- **Sign-in:** Claude Code, the Claude app, Codex and Grok sign in with your Motion Reel account, and you click Allow. No key.
- **With a key:** Cursor, OpenClaw, Hermes Agent and other clients send an API key in an Authorization: Bearer header.
- **Each app's steps:** Claude, Claude Code, Codex, Cursor, Grok, OpenClaw and Hermes Agent each have their own page. https://motionreel.app/agents

```
claude mcp add --transport http motionreel https://motionreel.app/mcp
```

## The REST API

The same operations over HTTP, for your own code.

- **Address:** https://motionreel.app/api/v1. GET https://motionreel.app/api/v1 lists every operation with its input, and needs no key.
- **Sign-in:** An API key in an Authorization: Bearer header on every call.
- **Input:** POST and PATCH take a JSON body. GET and DELETE take query parameters. An id is part of the path.
- **Times:** ISO 8601 with an offset, such as 2026-12-01T18:00:00-05:00, or "now". Times in answers are UTC.
- **Lists:** limit (1 to 100, 20 if left out) and offset.
- **OpenAPI:** The whole API as an OpenAPI 3.1 file, built from the same list. https://motionreel.app/openapi.json

```
curl https://motionreel.app/api/v1/me \
  -H "Authorization: Bearer YOUR_KEY"
```

## API keys

- **Where:** In the dashboard under Agents & API. A key belongs to one workspace and reaches only its accounts.
- **Read keys:** Look only: posts, numbers, comments, automations.
- **Write keys:** Also upload, post, set up automations and answer comments.
- **Revoking:** Revoke a key in the dashboard and it stops working at once. An agent that signed in is listed there too.

## Preview, then confirm

Anything that posts, messages or changes a post is checked first and comes back as a preview. It happens only when you send it again with confirm set to true.

- **Previews first:** create_post, update_post, retry_post, create_automation, update_automation, reply_to_comment, dm_commenter, hide_comment, delete_comment.
- **Acts at once:** start_upload, finish_upload, delete_media, cancel_post, dismiss_post, delete_automation.
- **No double posts:** Send an Idempotency-Key header (or idempotency_key) with create_post. The same key returns the first post instead of making a second.
- **For agents:** The preview tells the agent to show it to you and wait for your yes. An agent's confirm is refused without an idempotency key.

```
# 1. Check it. Nothing is scheduled; the answer is a preview.
curl https://motionreel.app/api/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"media_id": "MEDIA_ID", "account_ids": ["ACCOUNT_ID"], "caption": "Day 14", "when": "2026-12-01T18:00:00-05:00"}'

# 2. Schedule it: the same body with confirm, and a key so a retry can't post twice.
curl https://motionreel.app/api/v1/posts \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: day-14" \
  -d '{"media_id": "MEDIA_ID", "account_ids": ["ACCOUNT_ID"], "caption": "Day 14", "when": "2026-12-01T18:00:00-05:00", "confirm": true}'
```

## Getting a video in

MP4 or MOV, up to 300 MB. start_upload has three ways, by what you have.

- **A link:** Pass url, a direct https link to the file. Motion Reel downloads it and answers with a media id that's ready to post.
- **A file:** Pass size and type. The answer has a media id, a signed upload address and a curl command that sends the file in parts of 10 MB. Then call finish_upload.
- **On someone's phone:** Leave size and type out. The answer has page_url, a page where the person picks the file; it works for a day, for one file. Then call finish_upload.
- **How long it's kept:** Until every account has posted it. An upload no post uses is deleted after 24 hours; a draft keeps its file.

```
curl https://motionreel.app/api/v1/media \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/reel-14.mp4"}'
```

## Errors

Every error is JSON, {"error": {"code", "message"}}, with an HTTP status. The message says what happened and what to do.

- **400 invalid_input:** Something in the request was refused. The message says which part and why.
- **401 unauthorized:** No key, or one that was revoked. Send Authorization: Bearer and the key.
- **402 payment_required:** The workspace has no plan or trial. The message links to the plan page.
- **403 forbidden:** A read key tried to change something. Make a write key.
- **404 not_found:** Nothing with that id in this workspace, or no such endpoint.
- **409 conflict:** It can't be done as things stand, for example an account whose login expired. The message says what to fix.
- **429 rate_limited:** Too many calls. Wait for the Retry-After header's seconds, then try again.
- **500 internal_error:** Our side failed. Try again in a minute.

## Limits

- **API calls:** 120 a minute for a workspace's keys, REST and MCP together. More keys don't mean more calls.
- **Instagram posts:** 100 a day per account, counted across every app that posts to it. A post over the limit waits for room and says so.
- **Comment-to-DM:** Up to 8 DMs a minute per account, once per person per post. No monthly limit.
- **Everything else:** Video and caption sizes, daily limits, and what each failed post means are in the guide. https://motionreel.app/guide

## Where everything is

- **API reference:** Every operation with its input. https://motionreel.app/docs/api
- **Guide:** Every limit and rule. https://motionreel.app/guide
- **Connect your agent:** The steps for each app. https://motionreel.app/agents
- **For an agent to read:** One file that tells any agent how to connect and what the rules are. https://motionreel.app/SKILL.md
- **Help:** Answers to the questions people ask most. https://motionreel.app/help
