Skip to main content
API docs by Redocly

PinePods API (0.1.0)

Download OpenAPI specification:Download

License: GPL-3.0-or-later

HTTP API for the PinePods podcast server. Most endpoints require an Api-Key header tied to a user account; admin-only endpoints additionally require an admin (or web) key. This reference is generated directly from the backend source, so it stays in sync with the running code.

health

Health and instance checks (no auth)

Health check endpoint with database and Redis status GET /api/health

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "database": true,
  • "redis": true,
  • "timestamp": "2019-08-24T14:15:22Z"
}

PinePods instance check endpoint - matches Python API exactly GET /api/pinepods_check

Responses

Response samples

Content type
application/json
{
  • "status_code": 0,
  • "pinepods_instance": true
}

auth

Authentication, sessions, MFA, and OIDC

podcasts

Podcast subscriptions, episodes, queue, and playback

episodes

Episode actions: download, save, share, bulk ops

Download an episode media file

Authorizations:
api_key
path Parameters
episode_id
required
integer <int32>

Episode ID to download

query Parameters
api_key
string

API key (alternative to the Api-Key header)

Responses

playlists

Smart and manual playlists

Create a playlist

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
name
required
string
description
string or null
podcast_ids
Array of integers or null <int32> [ items <int32 > ]
include_unplayed
required
boolean
include_partially_played
required
boolean
include_played
required
boolean
play_progress_min
number or null <double>
play_progress_max
number or null <double>
time_filter_hours
integer or null <int32>
min_duration
integer or null <int32>
max_duration
integer or null <int32>
sort_order
required
string
group_by_podcast
required
boolean
max_episodes
integer or null <int32>
icon_name
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "name": "string",
  • "description": "string",
  • "podcast_ids": [
    ],
  • "include_unplayed": true,
  • "include_partially_played": true,
  • "include_played": true,
  • "play_progress_min": 0,
  • "play_progress_max": 0,
  • "time_filter_hours": 0,
  • "min_duration": 0,
  • "max_duration": 0,
  • "sort_order": "string",
  • "group_by_podcast": true,
  • "max_episodes": 0,
  • "icon_name": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string",
  • "playlist_id": 0
}

Delete a playlist

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
playlist_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "playlist_id": 0
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

Update a playlist

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
playlist_id
required
integer <int32>
name
required
string
description
string or null
podcast_ids
Array of integers or null <int32> [ items <int32 > ]
include_unplayed
required
boolean
include_partially_played
required
boolean
include_played
required
boolean
play_progress_min
number or null <double>
play_progress_max
number or null <double>
time_filter_hours
integer or null <int32>
min_duration
integer or null <int32>
max_duration
integer or null <int32>
sort_order
required
string
group_by_podcast
required
boolean
max_episodes
integer or null <int32>
icon_name
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "playlist_id": 0,
  • "name": "string",
  • "description": "string",
  • "podcast_ids": [
    ],
  • "include_unplayed": true,
  • "include_partially_played": true,
  • "include_played": true,
  • "play_progress_min": 0,
  • "play_progress_max": 0,
  • "time_filter_hours": 0,
  • "min_duration": 0,
  • "max_duration": 0,
  • "sort_order": "string",
  • "group_by_podcast": true,
  • "max_episodes": 0,
  • "icon_name": "string"
}

Response samples

Content type
application/json
{
  • "detail": "string"
}

settings

User and server settings

sync

gpodder / Nextcloud synchronization

tasks

Background tasks and progress

feed

Public RSS feed generation

proxy

Media and image proxying

local

Local podcasts and media

youtube

YouTube channel integration