Back to AI Overview

REST API Reference

A complete guide to programmatically managing your Repodcast feeds.

Authentication

All API requests must include your API key in the Authorization header. You can generate a key in your Settings page.

Authorization: Bearer repodify_live_YOUR_KEY

You can also download our OpenAPI swagger.json specification to import into Postman or Insomnia.

Standard Errors

If an API request fails, it will return an appropriate HTTP status code and a JSON body containing an error string explaining what went wrong.

{
  "error": "Missing or invalid Authorization header"
}
  • 400 Bad Request: Missing required fields (like name or audioUrl)
  • 401 / 403 Unauthorized: Invalid or missing API key
  • 404 Not Found: The feed or episode does not exist, or you don't own it
  • 500 Internal Error: Server-side processing failure

Feeds

GET/api/v1/feeds

Returns a list of all Repodcast feeds associated with your account.

Success Response (200 OK)

{
  "feeds": [
    {
      "id": "abc123xyz",
      "name": "My Tech Podcast",
      "slug": "my-tech-podcast",
      "feedUrl": "https://repodify.app/api/feed/my-tech-podcast"
    }
  ]
}
GET/api/v1/feeds/[slug]

Returns the metadata for a specific feed along with an ordered array of all its episodes.

Success Response (200 OK)

{
  "feed": {
    "id": "abc123xyz",
    "name": "My Tech Podcast",
    "slug": "my-tech-podcast",
    "episodes": [
      {
        "id": "ep_123",
        "title": "Episode 1: The Beginning",
        "audioUrl": "https://example.com/audio.mp3",
        "sortOrder": 0
      }
    ]
  }
}

Error Response (404 Not Found)

{
  "error": "Feed not found or access denied"
}
GET/api/v1/feeds/[slug]/stats

Retrieves deep analytics for a feed, merging XML fetches with actual MP3 plays. Custom date ranges are required via query parameters.

Query Parameters

  • start (required): ISO date string (e.g., 2026-01-01)
  • end (required): ISO date string (e.g., 2026-01-31)

Success Response (200 OK)

{
  "slug": "my-tech-podcast",
  "range": {
    "start": "2026-01-01T00:00:00.000Z",
    "end": "2026-01-31T23:59:59.999Z"
  },
  "totalFeedDownloads": 1250,
  "totalEpisodeDownloads": 840,
  "timeseries": [
    {
      "date": "2026-01-01",
      "feedAccesses": 45,
      "episodeDownloads": 23,
      "episodes": [
        { "episodeId": "ep_123", "count": 13 },
        { "episodeId": "ep_456", "count": 10 }
      ],
      "countries": [
        { "country": "US", "count": 10 }
      ],
      "userAgents": [
        { "userAgent": "Apple Podcasts", "count": 15 }
      ]
    }
  ],
  "isPremium": true,
  "countries": [
    { "country": "US", "count": 500 },
    { "country": "GB", "count": 120 }
  ],
  "userAgents": [
    { "userAgent": "Apple Podcasts", "count": 400 },
    { "userAgent": "Spotify", "count": 350 }
  ],
  "status": "active"
}

Error Response (400 Bad Request)

{
  "error": "Missing required query parameters: start and end"
}
POST/api/v1/feeds

Creates a new Repodcast feed.

Request Body

{
  "name": "My Tech Podcast",
  "description": "Optional description for the feed."
}

Success Response (201 Created)

{
  "message": "Feed created successfully",
  "feed": { 
    "id": "abc123xyz",
    "slug": "my-tech-podcast-xyz123" 
  }
}

Error Response (400 Bad Request)

{
  "error": "Missing required field: name"
}
PATCH/api/v1/feeds/[slug]

Updates the metadata (name, description, imageUrl) of a feed.

Request Body

{
  "name": "Daily Tech News",
  "imageUrl": "https://example.com/cover-art.jpg"
}

Success Response (200 OK)

{
  "message": "Feed updated successfully",
  "updates": {
    "name": "Daily Tech News",
    "imageUrl": "https://example.com/cover-art.jpg"
  }
}
POST/api/v1/feeds/[slug]/submit

Submits the feed to the global PodcastIndex directory.

Success Response (200 OK)

{
  "message": "Feed submitted to PodcastIndex successfully",
  "feedUrl": "https://repodify.app/api/feed/my-tech-podcast"
}

Error Response (500 Server Error)

{
  "error": "Failed to submit feed to PodcastIndex"
}
DELETE/api/v1/feeds/[slug]

Permanently deletes a Repodcast and all of its associated episodes.

Success Response (200 OK)

{
  "message": "Feed and all episodes deleted successfully"
}

Episodes

POST/api/v1/feeds/[slug]/episodes

Adds a new audio episode to a specific feed.

Request Body

{
  "title": "Episode 1: The Beginning",
  "audioUrl": "https://example.com/audio.mp3",
  "description": "Optional episode notes"
}

Success Response (201 Created)

{
  "message": "Episode added successfully",
  "episodeId": "ep_123"
}
POST/api/v1/feeds/[slug]/episodes/upload

Directly uploads a raw MP3 file to cloud storage and attaches it to a new episode in a single request. Send as multipart/form-data.

Form Data Fields

  • file (required): The raw audio file (.mp3, .m4a)
  • title (required): The title of the episode
  • description (optional): The description of the episode

Success Response (201 Created)

{
  "message": "Episode uploaded and added successfully",
  "episodeId": "ep_456",
  "audioUrl": "https://repodify-audio-files.s3.amazonaws.com/[email protected]/123-audio.mp3"
}

Error Response (403 Forbidden)

{
  "error": "Account storage limit exceeded. Max: 100MB."
}
PATCH/api/v1/feeds/[slug]/episodes/[id]

Updates the metadata or media for a specific episode.

Request Body

{
  "title": "Episode 1: Updated Title",
  "description": "Updated notes",
  "audioUrl": "https://example.com/new-audio.mp3",
  "imageUrl": "https://example.com/new-episode-art.jpg"
}

Success Response (200 OK)

{
  "message": "Episode updated successfully",
  "updates": {
    "title": "Episode 1: Updated Title",
    "description": "Updated notes",
    "audioUrl": "https://example.com/new-audio.mp3",
    "imageUrl": "https://example.com/new-episode-art.jpg"
  }
}
PUT/api/v1/feeds/[slug]/episodes/reorder

Bulk reorders the episodes in a feed.

Request Body

{
  "orderedIds": ["ep_123", "ep_456", "ep_789"]
}

Success Response (200 OK)

{
  "message": "Episodes reordered successfully"
}

Error Response (400 Bad Request)

{
  "error": "Validation failed: Feed contains 3 episodes, but 2 IDs were provided."
}
DELETE/api/v1/feeds/[slug]/episodes/[id]

Deletes a specific episode from a feed.

Success Response (200 OK)

{
  "message": "Episode deleted successfully"
}

Error Response (404 Not Found)

{
  "error": "Episode not found"
}

Profile

PATCH/api/v1/profile

Updates the authenticated user's public profile metadata.

Request Body

{
  "displayName": "Jonathan Roig",
  "bio": "Podcast creator and software engineer.",
  "imageUrl": "https://example.com/avatar.jpg"
}

Success Response (200 OK)

{
  "message": "Profile updated successfully",
  "updates": {
    "displayName": "Jonathan Roig",
    "bio": "Podcast creator and software engineer.",
    "imageUrl": "https://example.com/avatar.jpg"
  }
}
POST/api/v1/profile/upload

Directly uploads an image to cloud storage, automatically resizes and compresses it, sets it as the user's avatar, and deletes the previous avatar from storage. Send as multipart/form-data.

Form Data Fields

  • file (required): The raw image file (.jpg, .png)

Success Response (201 Created)

{
  "message": "Profile image updated successfully",
  "imageUrl": "https://repodify-image-files.s3.amazonaws.com/[email protected]/123-avatar.jpg"
}

Media

POST/api/upload

Uploads an image or audio file to cloud storage and returns a public URL. Use this to host cover art or avatars before passing the URL to other API endpoints. Send as multipart/form-data.

Form Data Fields

  • file (required): The raw file
  • type (optional): image or audio (defaults to audio)

Success Response (200 OK)

{
  "url": "https://repodify-image-files.s3.amazonaws.com/[email protected]/123-cover.jpg"
}