You can upload and manage the media files (images, audio, video) that your scenario and campaign actions attach. Upload them up front through the API, or attach one inline while you build a scenario by passing a URL, with no separate upload step. That inline path also works when your AI agent builds a scenario for you.
Before you start
You'll need a Pro or Trial account and your API token. See The Inrō Private API: Getting Started for auth.
Manage media files
These endpoints are under /api/v1/media_files:
GET /api/v1/media_fileslists your media files. Filter bymedia_type(image, audio, video, and more) and page through the results.POST /api/v1/media_filesuploads a file. Provide either a multipartfileor afile_urlthat Inrō downloads for you. Themedia_typeis detected automatically when you usefile_url. You can also add acaption.GET /api/v1/media_files/:idfetches one media file by its ID.
Attach media inline to an action
You don't have to upload first. When you create or update a scenario, the media_file field on an action takes one of two shapes:
{ "id": 123 }references a media file you already uploaded.{ "file_url": "https://..." }downloads and stores a new one inline, then links it to the action in the same request.
The same works inside conversion_link objects, so you can give a link card a cover image inline.
Where this works:
Scenario actions: over both the API and MCP.
Campaign actions: over the API only. (The MCP campaign tools don't carry inline objects, so upload first with
POST /api/v1/media_filesand reference the file byid.)
Have your AI agent attach media
Because inline media_file works through the scenario tools, you can ask your connected agent to build a media-rich scenario in one go:
"Create a welcome scenario that sends the image at https://mybrand.com/welcome.jpg when someone DMs me 'hello'"
Your agent calls create_scenario with media_file: { file_url: "..." } on the send-photo action. Inrō downloads the image, stores it, and links it to the action, all in a single request.
🐾 Netsuke's Tips
Reusing the same image across many scenarios? Upload it once with
POST /api/v1/media_files, then reference it byidinstead of passing the URL every time.When you upload with
file_url, Inrō reads the file's content type to setmedia_type. If a file comes back with the wrong type, check that the URL serves the rightContent-Typeheader.For sending media straight to a contact (rather than attaching it to an action), see Send Rich Messages via API & MCP.
What's next?
Build and Update Automations Programmatically via API & MCP to attach media while building a scenario.
Send Rich Messages via API & MCP: Images, Videos, Audio, Posts to send media directly to contacts.
Message Actions: Text, Media, Files & Buttons for how media actions work in a scenario.