Motion Reel logoMotion Reel

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.