> For the complete documentation index, see [llms.txt](https://docs.podigee.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-media-uploads-and-encoding.md). # REST API media uploads and encoding Endpoints for upload URLs, productions, media clips, and batch encodings in the REST API v1. Use this reference when you need the exact endpoints to upload a media file, attach it to an episode, start encoding, or read the encoded files. Paths are relative to `https://app.podigee.com/api/v1`. The normal flow has three stages: 1. Request an upload URL with `POST /uploads` and upload the file to that URL. 2. Create a production for the episode with the returned `file_url`. 3. Start the production with `POST /productions/{production_id}/start`. These endpoints are not the media upload protocol of the Model Context Protocol (MCP) server. [Upload local media with an HTTP client](/documentation/start-here/ai-agents/transfer-media-encode-and-publish/upload-local-media-with-an-http-client.md) documents the agent protocol. ## Uploads | Method | Path | Purpose | Notable parameters | Response notes | | ------ | --------------------------------- | --------------------------------------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `POST` | `/uploads` | Get a signed URL to upload one file to storage | `filename` (required), `filesize`, `idempotency_key`, `upload_type` | Returns `upload_url`, `content_type`, `file_url`, and `multipart_upload`. For a file larger than 30 MB, also `upload_key`, `part_size` (`31457280`), and `multipart_upload_id`. | | `POST` | `/uploads/part_url` | Get a signed URL for one part of a multipart upload | Part details of the upload | `422` with `URL generation failed` or the validation message. | | `POST` | `/uploads/complete_multipart_url` | Get the URL that completes a multipart upload | Upload details | `422` with `URL generation failed` or the validation message. | ### Upload parameters and limits | Item | Value | | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `upload_type` | `public` (default), `private`, or `temporary` | | `idempotency_key` | Stable key to retry the same upload without a change of its URL. `1` to `128` characters from letters, digits, `.`, `_`, `:`, and `-`. The key must start with a letter or a digit | | Upload method | Send the file with `PUT` to `upload_url` | | `upload_url` validity | 3600 seconds | | Maximum file size | 20 GB | | Accepted file extensions | See [Upload audio or video](/documentation/create-and-publish/production/episodes/upload-audio-or-video.md) | ### Upload errors | Status | Message | Cause | | ------ | --------------------------------------- | --------------------------------------------- | | `422` | `File size exceeds the maximum allowed` | `filesize` is above 20 GB. | | `422` | `Unsupported content type` | The file extension has no known content type. | | `422` | `Invalid upload idempotency key` | The key does not match the allowed pattern. | ## Productions A production attaches one uploaded file to an episode and controls its encoding. | Method | Path | Purpose | Notable parameters | Response notes | | -------- | ------------------------------------ | ---------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------- | | `GET` | `/productions/{production_id}` | Read a production | none | Includes `state`, `files`, and `audio_duration_ms`. | | `POST` | `/productions` | Create a production for an episode | `episode_id`, `state`, `publication_flag` | | | `PUT` | `/productions/{production_id}` | Update a production | `state`, `publication_flag` | | | `DELETE` | `/productions/{production_id}` | Delete a production | none | | | `POST` | `/productions/{production_id}/start` | Start encoding | `publish_episode=true` publishes the episode after encoding | `402` with `Not enough encoding time left` when the plan has no encoding time left. | | `POST` | `/productions/{production_id}/stop` | Stop encoding | none | | ### Production states | State | Meaning | | ---------- | ----------------------------------------- | | `initial` | The production exists and is not encoded. | | `encoding` | Encoding runs. | | `encoded` | Encoding finished. | | `error` | Encoding failed. | Use `/start` and `/stop` to control encoding. The start of a production requires that the account has permission to encode media for that podcast. ## Media clips A media clip is one encoded file of an episode, or a file that is hosted outside Podigee. | Method | Path | Purpose | Notable parameters | Response notes | | -------- | ------------------------------ | ---------------------------------- | ------------------------------------------------------ | ------------------------------------- | | `GET` | `/media_clips` | List the media clips of an episode | `episode_id` | Returns only supported audio formats. | | `GET` | `/media_clips/{media_clip_id}` | Read a media clip | none | | | `POST` | `/media_clips` | Register a file for an episode | `episode_id`, `file_format`, `url`, `size`, `duration` | | | `DELETE` | `/media_clips/{media_clip_id}` | Delete a media clip | none | | Error: `404` with `The media_clip with id could not be found.` ## Batch encodings Batch encoding re-encodes every episode of a podcast after you changed the intro or outro audio. | Method | Path | Purpose | Notable parameters | Response notes | | ------ | ------------------------ | ----------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------- | | `GET` | `/batch_encodings` | Read the progress of the latest batch encoding of a podcast | `podcast_id` (required) | `404` without a body when the podcast has no batch encoding. | | `GET` | `/batch_encodings/state` | Read the intro and outro encoding state | `podcast_id` (required) | Returns `{"state": "..."}`. | | `POST` | `/batch_encodings` | Start a batch encoding for a podcast | `podcast_id` (required), `initiator` | `200` without a body. `422` with `Wrong initiator parameter value` when `initiator` is not a valid value. | Every batch encoding request needs `podcast_id`. An unknown podcast answers `404` with `The podcast with id could not be found.` ## Related pages * [REST API podcasts and episodes](/documentation/connect-and-administer/integrations/rest-api/rest-api-podcasts-and-episodes.md) * [REST API episode content](/documentation/connect-and-administer/integrations/rest-api/rest-api-episode-content.md) manages the intro and outro audio. * [REST API authentication and errors](/documentation/connect-and-administer/integrations/rest-api/rest-api-authentication-and-errors.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.podigee.com/documentation/connect-and-administer/integrations/rest-api/rest-api-media-uploads-and-encoding.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.