Attaching files

You can hand your agent a file — a reference photo for a character, a product shot, a brand style guide, a voice sample to clone, a script, a rough cut — and have it reach Popcorn.

It takes two steps, and your agent needs to know both. MCP tool arguments are JSON, and the protocol has no way to carry a file into a tool call, so the bytes travel over a plain HTTP request first. Your agent then puts the resulting link in an ordinary message.

Step 1 — Upload the file

curl -sS -F "file=@/path/to/reference.png" https://api.popcorn.co/api/v1/uploads

{
  "url": "https://media.popcorn.co/mcp-uploads/source/V1StGXR8Z5jd.png",
  "filename": "reference.png",
  "mime_type": "image/png",
  "size_bytes": 51244
}

Method	POST https://api.popcorn.co/api/v1/uploads
Body	multipart/form-data with a single file field
Auth	None needed — see why below
Accepted	Images, video, audio, PDF, plain text, Markdown
Limit	25 MB, one file per request

For several files, repeat the call and reference all the URLs in one message.

Failures come back as { "success": false, "error": "…", "code": "VALIDATION_ERROR" } — most often an unsupported file type or a file over the size cap.

Step 2 — Reference the URL in a message

Uploading alone does nothing. The file only reaches Popcorn when your agent sends the URL in a message, along with a note about what it is and how it should be used:

send_movie_message(movie_id, "Use this product shot in scene 2: <url>")

or, if your agent has the Showrunner tools:

send_message_to_project_showrunner(project_id, "Reference photo for Mara — use it as her look: <url>")

The receiving agent downloads the file into its own workspace, after which it can view, transcribe, or analyze it exactly as if you had attached it in the web chat — and it stays available on later turns.

Say what the file is for. A bare URL with no context is much less useful than “this is the reference photo for Mara, use it as her look”. The receiving agent decides what to do with the file based on what you tell it.

Telling your agent to do this

Most agents will not think to upload a file on their own. Either install the Popcorn skill, which teaches this flow, or say it plainly:

Upload this image to Popcorn and send it to my Showrunner as the reference for Mara’s look.

Watch out for one failure mode: an agent that can see your image may describe it in words instead of uploading it. A prose description is not a substitute — the receiving agent cannot see what your agent saw. If you get a movie that ignored your reference, check whether the file was actually uploaded.

Why no API key?

The upload endpoint is deliberately open, and it takes no project or movie id. Two things make that safe:

• An upload is inert on its own. It puts bytes at an unguessable address and nothing more. Nobody is notified, and it is not attached to anything.
• Delivery is where permission is checked. Getting a file into a project still goes through the message tools, which verify you have write access and refuse a non-member.

Because the two steps are separate, an anonymous upload cannot reach anyone’s project.

Uploaded files are not currently deleted, so treat the URLs as durable — but also as effectively public to anyone who has the link. Don’t upload anything you wouldn’t want shared that way.