Tools reference

Once your agent is connected, it has access to the Popcorn tools. They come in two groups.

Movies and account — always available:

Tool	What it does
create_movie	Starts a new movie from a natural-language brief. Returns immediately with an id.
get_movie	Polls a movie’s status. When complete, returns the video URL.
send_movie_message	Sends a follow-up message to an existing movie — same as typing in the studio chat.
get_movie_messages	Reads the recent chat transcript so the agent can see Popp’s reply.
list_movies	Lists past movies, newest first.
search_elements	Finds your reusable characters, props, and sets to tag into a movie.
get_balance	Your remaining credits.
get_user_plan	Your subscription and plan details.

Showrunner projects — only when the connection has the showrunner permission:

Tool	What it does
list_projects	Lists your Showrunner projects, newest first.
get_project	One project: title, your role, and the Showrunner’s onboarding status.
get_project_chat_threads	The project’s chat threads, most recently active first.
send_message_to_project_showrunner	Talks to the Showrunner, exactly as you would in the project chat.
get_project_chat_messages	Reads a thread’s transcript to see the reply.

A security token connection has both groups. An OAuth connection has the project tools only if you granted the showrunner permission when you approved it. Agents should check their own tool list rather than assume.

Files are not in either group — there is no upload tool, because MCP tool arguments are JSON. See Attaching files.

Movies and account

create_movie

Kicks off a new movie from a natural-language brief. Returns immediately with a movie id; the movie then runs asynchronously for several minutes (typically 3–10 min). Don’t hold the call open waiting for it.

Input:

Field	Type	Description
brief	string	What you want made. Be specific about format.
duration	number?	Target duration in seconds, 5–120. Defaults to ~30.
orientation	string?	landscape, portrait, or square.
style	string?	Free-form style hint, e.g. “cinematic noir”, “flat 2D animation”.
tagged_elements	array?	Up to 10 elements from search_elements to bring into the movie.

Returns: { id, status, created_at } — the movie is now being produced.

Tip for agents: be specific about format in the brief. “10-second reaction video to https://youtu.be/…”, ”30s UGC ad for <product>”, ”15s clip starting at 1:23 of <url> with new narration over it” all produce much better results than “make a video about X”.

get_movie

Polls the status of a movie. Call this every 15–30 seconds while the movie is running.

Input: { id }

Returns:

Field	Description
status	running, completed, or failed
video_url	URL of the finished video (when completed)
studio_url	Link to the editable studio page (when completed)
error	Reason for failure (when failed)

CRITICAL — completed without a video

If status is completed but video_url is missing or null, the movie agent stopped before delivering the final video. Do not report success. Instead, call send_movie_message(id, "...") asking why there’s no final video and whether the agent can continue producing it. Then resume polling.

This pattern means Popp likely needs a nudge to finish.

send_movie_message

Sends a follow-up chat message to an existing movie — the same effect as typing in the studio chat. Popp runs a new turn asynchronously (it can revise the script, regenerate a shot, swap music, etc.).

Input:

Field	Type	Description
id	string	The movie id.
message	string	What to tell Popp.
tagged_elements	array?	Elements from search_elements to bring in.

Returns: an acknowledgement that the message was received.

After sending a message, resume polling get_movie until the new turn settles, then call get_movie_messages to read what Popp did.

Sending a file: there is no file parameter — MCP tool arguments are JSON and cannot carry one. Upload the file to POST https://api.popcorn.co/api/v1/uploads first and paste the returned URL into message, saying what the file is and how Popp should use it. Popp fetches it itself. See Attaching files.

get_movie_messages

Reads the recent chat transcript so you can see Popp’s reply after sending a message.

Input: { id, limit? } — limit defaults to 50, capped at 200.

Returns: an array of recent messages between you and Popp.

Useful after send_movie_message to see what Popp actually changed, what tools it ran, and whether it has any clarifying questions back.

list_movies

Lists your existing movies, most recent first. Use it to find a movie to revisit, or to summarize what you’ve made.

Input: { limit?, offset? }

Returns: id, title, stage, created_at, updated_at per movie, plus total and has_more. A stage of complete means the video is finished; any other stage means it’s mid-production or was abandoned.

search_elements

Searches or browses your element library — reusable characters, props, and sets — for things to tag into a movie.

Input: { query?, type?, movie_id?, limit? }. Omit query to browse.

Returns: matching elements with ids suitable for tagged_elements.

Agents should call this whenever you mention an existing element by name or with an @ reference, then pass the chosen results straight into create_movie or send_movie_message as tagged_elements.

get_balance

Input: none. Returns: credits (integer remaining), an optional warning when the balance is low, and top_up_url.

get_user_plan

Input: none. Returns: subscription (plan name, status, period end, trial info), manage_url, and an optional message explaining why subscription is null.

Showrunner projects

These tools only appear when the connection has the showrunner permission. A project is an ongoing body of video work with an AI Showrunner managing it — distinct from a single movie, which is one conversation that produces one video.

list_projects

Input: { limit?, offset? }. Returns: id, title, your role on the project, and timestamps, plus total and has_more. This is where the project id the other tools need comes from.

get_project

Input: { project_id }. Returns: the project’s title, your role, and the Showrunner managing it — name, job title, and onboarding status.

An onboarding status other than complete means the Showrunner is still getting set up and may not be ready to work yet.

get_project_chat_threads

Input: { project_id }. Returns: the project’s chat threads, most recently active first.

A project’s chat is shared by everyone with access to it and can hold several parallel conversations. You usually don’t need this — the two tools below default to the most recently active thread.

send_message_to_project_showrunner

Talks to the Showrunner exactly as you would in the project chat.

Input: { project_id, message, thread_id? }

Returns: as soon as the message is durably accepted, with the thread_id it landed in. The Showrunner’s turn then runs asynchronously and can take minutes, because it may commission entire movies. Never wait on this call — poll get_project_chat_messages instead. Messages queue in order, so a turn already running doesn’t need a retry.

Requires write access to the project. A read-only member gets the same “Project not found” error as a non-member.

Sending a file: upload it first and put the URL in message — see Attaching files. This is the normal way to give a project reference imagery for its characters, sets, and props.

get_project_chat_messages

Reads a thread’s transcript, newest first. Poll every 15–30 seconds after sending.

Input: { project_id, thread_id?, limit?, before_index? }

Returns: the messages, plus next_before_index for paging into older history. A project nobody has talked to yet returns an empty list and a null thread_id.

Typical flows

New movie, end-to-end

1. create_movie(brief)  →  { id: "abc-123" }
2. get_movie("abc-123") every 15-30s until status == "completed"
3. Hand back video_url and studio_url to the user

Iterate on an existing movie

1. send_movie_message(id, "make scene 2 more dramatic")
2. get_movie(id) every 15-30s until status == "completed" again
3. get_movie_messages(id) to read Popp's reply
4. Hand back the new video_url

Use an existing character, prop, or set

1. search_elements("Wizard Cat")  →  pick the right match
2. create_movie(brief, tagged_elements: [<that element>])
3. Poll as usual

Send a reference file

1. POST the file to https://api.popcorn.co/api/v1/uploads  →  { url: "..." }
2. send_movie_message(id, "Use this product shot in scene 2: <url>")
3. get_movie(id) every 15-30s until the turn settles

Direct a Showrunner

1. list_projects()                                        → pick { id }
2. get_project(project_id)                                → confirm onboarding is complete
3. send_message_to_project_showrunner(project_id, "...")  → returns immediately
4. get_project_chat_messages(project_id) every 15-30s     → newest assistant message is the reply

Studio link

Every movie is also viewable and editable in the Popcorn studio at:

https://www.popcorn.co/studio/{movie_id}

get_movie returns this as studio_url once the movie is completed. Agents are encouraged to share it alongside the video URL so you can open the movie in the studio at any time.

Want more?

For deeper integration, the Popcorn skill packages all the patterns above — polling intervals, error recovery, element tagging, file attachments, studio links — into a drop-in skill for any agent that supports them.