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.
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
nameoraudioUrl) - 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
/api/v1/feedsReturns 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"
}
]
}/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"
}/api/v1/feeds/[slug]/statsRetrieves 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"
}/api/v1/feedsCreates 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"
}/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"
}
}/api/v1/feeds/[slug]/submitSubmits 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"
}/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
/api/v1/feeds/[slug]/episodesAdds 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"
}/api/v1/feeds/[slug]/episodes/uploadDirectly 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."
}/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"
}
}/api/v1/feeds/[slug]/episodes/reorderBulk 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."
}/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
/api/v1/profileUpdates 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"
}
}/api/v1/profile/uploadDirectly 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
/api/uploadUploads 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):
imageoraudio(defaults to audio)
Success Response (200 OK)
{
"url": "https://repodify-image-files.s3.amazonaws.com/[email protected]/123-cover.jpg"
}