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.
Updated November 17, 2026. Also in Markdown at /docs.md.
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.
- 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.
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.
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.
Where everything is
- API reference
- Every operation with its input.
- Guide
- Every limit and rule.
- Connect your agent
- The steps for each app.
- For an agent to read
- One file that tells any agent how to connect and what the rules are.
- Help
- Answers to the questions people ask most.
Motion Reel