Media Management API

This document describes the REST API endpoints for podcast media processing.

Base URL

https://api.studio.inlet.fm

Authentication

All API endpoints require authentication using a Token in the Authorization header. The API key is associated with the user and grants access to all podcasts owned by that user.

Authorization: Token <API_KEY>

Endpoints

1. Process Media

POST https://api.studio.inlet.fm/api/v1/podcasts/:podcastId/media/process

Triggers a media processing flow for a given media URL. The system will process the media for ad break detection and insertion according to the podcast's configuration.

Request Body

{
  "url": "https://some.server.com/media.mp3",
  "name": "Media title",
  "description": "Media description. Links are supported: www.google.com", // (optional)
  "publishedDate": "2025-10-01T14:30:00.000Z", // (optional)
  "adOptions": {} // (optional) see below
}

Request Body Fields

type MediaCreationParams = {
  url: string;
  name: string;
  description?: string;
  adOptions?: AdOptions;
  publishedDate?: string;
}

Ad Options

Ad Options allow you to customize the ad injection experience.

Each of the options above can be further customized as follows:

type AdConfiguration = {
  minDuration?: number;
  maxDuration?: number;
  adCount: number;
}

type AutomatedMidRollOption = {
  minDuration?: number;
  maxDuration?: number;
  adCount: number;
  insertionCount?: number;
  adsPerHour?: number;
}

type MidRollOption = {
  minDuration?: number;
  maxDuration?: number;
  adCount: number;
  time: number;
}

type AdOptions = {
  preRoll?: AdConfiguration;
  postRoll?: AdConfiguration;
  automatedMidRolls?: AutomatedMidRollOption;
  midRolls?: MidRollOption[];
}

Example Requests

1. Uploading media with automatedMidRolls options of 3 ads to be played at a rate of 2 ad breaks per hour.

curl -X POST https://api.studio.inlet.fm/api/v1/podcasts/507f1f77bcf86cd799439011/media/process \
  -H "Authorization: Token your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/media/episode.mp3",
    "name": "My Podcast Episode",
    "adOptions": {
      "preRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "postRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "automatedMidRolls": {
        "adCount": 3,
        "adsPerHour": 2
      }
    }
  }'

1. Uploading media with automatedMidRolls options of 4 ad breaks to be detected with 2 ads to be played at each ad break.

curl -X POST https://api.studio.inlet.fm/api/v1/podcasts/507f1f77bcf86cd799439011/media/process \
  -H "Authorization: Token your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/media/episode.mp3",
    "name": "My Podcast Episode",
    "adOptions": {
      "preRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "postRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "automatedMidRolls": {
        "adCount": 2,
        "insertionCount": 4
      }
    }
  }'

1. Uploading media with midRolls - which allows for custom placement of midroll ads in the media file. Each midroll can be customized with the minimum duration: minDuration, maximumDuration :maxDuration, and the number of ads to be played: adCount. With this example, an ad break is inserted at the 5 second mark and 90 second mark.

curl -X POST https://api.studio.inlet.fm/api/v1/podcasts/507f1f77bcf86cd799439011/media/process \
  -H "Authorization: Token your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/media/episode.mp3",
    "name": "My Podcast Episode",
    "adOptions": {
      "preRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "postRoll": {
        "adCount": 1,
        "minDuration": 15,
        "maxDuration": 30
      },
      "midRolls": [
        {
          maxDuration?: 15;
          adCount: 1;
          time: 5;
        },
        {
          maxDuration?: 15;
          adCount: 1;
          time: 90;
        },
      ]
    }
  }'

Response

{
  "success": true,
  "message": "Media processing started successfully",
  "data": {
    "mediaId": "507f1f77bcf86cd799439012",
    "status": "AD_BREAK_QUEUED",
    "name": "My Podcast Episode",
    "originUrl": "https://example.com/media/episode.mp3"
  }
}

2. Check Media Status

GET https://api.studio.inlet.fm/api/v1/podcasts/:podcastId/media/:mediaId

Retrieves the current status and details of a media processing job.

Example Request

curl -X GET https://api.studio.inlet.fm/api/v1/podcasts/507f1f77bcf86cd799439011/media/507f1f77bcf86cd799439012 \
  -H "Authorization: Token your-api-key-here"

Response

{
  "success": true,
  "data": {
    "mediaId": "507f1f77bcf86cd799439012",
    "name": "My Podcast Episode",
    "status": "READY",
    "originUrl": "https://example.com/media/episode.mp3",
    "url": "https://processed-media-url.com/episode.mp3",
    "duration": 1800,
    "publishedDate": "2024-01-15T10:30:00.000Z",
    "createdAt": "2024-01-15T10:00:00.000Z",
    "updatedAt": "2024-01-15T10:25:00.000Z",
    "failedAttempts": 0,
    "adRemovalMarkers": []
  }
}

Status Values

The status field in responses can have the following values:

Error Responses

All endpoints return consistent error responses:

{
  "error": "Error Type",
  "message": "Detailed error message"
}

Common HTTP Status Codes

Processing Flow

The media processing follows this general flow:

1. Media Upload/Reference: Media is referenced by URL and a MediaSource record is created
2. Ad Break Detection: The system analyzes the media for optimal ad break placement
3. Ad Insertion: Ads are inserted at detected or specified break points
4. Publishing: Processed media is published to configured platforms
5. Ready: Media is available for distribution

The initial status after submitting media is AD_BREAK_QUEUED, which indicates the media has been queued for ad break analysis.

Polling for Status

To monitor the progress of a media processing job, poll the status endpoint:

# Poll every 30 seconds
while true; do
  curl -X GET https://api.studio.inlet.fm/api/v1/v1/podcasts/507f1f77bcf86cd799439011/media/507f1f77bcf86cd799439012 \
    -H "Authorization: Token your-api-key-here"
  sleep 30
done

Setting Up API Keys

To enable API access, you need to generate an API key for your user account. This can be done through the GraphQL API:

mutation GenerateApiKey {
  generateApiKey
}

The API key is associated with the user and grants access to all podcasts owned by that user. You can also query your current API key:

query MyApiKey {
  myApiKey
}

Rate Limiting

Currently, there are no rate limits implemented, but it's recommended to:

Notes