Skip to main content
API docs by Redocly

PinePods API (0.9.1)

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

Oidc callback

query Parameters
code
string or null
state
string or null
error
string or null
error_description
string or null

Responses

Store oidc state

Request Body schema: application/json
required
state
required
string
client_id
required
string
origin_url
string or null
code_verifier
string or null
redirect_uri
string or null

Responses

Request samples

Content type
application/json
{
  • "state": "string",
  • "client_id": "string",
  • "origin_url": "string",
  • "code_verifier": "string",
  • "redirect_uri": "string"
}

Response samples

Content type
application/json
null

Get config

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "api_url": "string",
  • "proxy_url": "string",
  • "proxy_host": "string",
  • "proxy_port": "string",
  • "proxy_protocol": "string",
  • "reverse_proxy": "string",
  • "people_url": "string"
}

Create first admin

Request Body schema: application/json
required
username
required
string
password
required
string
email
required
string
fullname
required
string

Responses

Request samples

Content type
application/json
{
  • "username": "string",
  • "password": "string",
  • "email": "string",
  • "fullname": "string"
}

Response samples

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

First login done

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get auto complete seconds

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get key

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "retrieved_key": "string",
  • "mfa_required": true,
  • "user_id": 0,
  • "mfa_session_token": "string"
}

Get theme

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get user

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "status": "string",
  • "retrieved_id": 0
}

Import opml

Authorizations:
api_key
Request Body schema: application/json
required
podcasts
required
Array of strings
user_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcasts": [
    ],
  • "user_id": 0
}

Response samples

Content type
application/json
null

Import progress

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get public oidc providers

Responses

Response samples

Content type
application/json
{
  • "providers": [
    ],
  • "disable_standard_login": true
}

Reset password create code

Request Body schema: application/json
required
email
required
string
username
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "username": "string"
}

Response samples

Content type
application/json
{
  • "code_created": true
}

Get self service status

Responses

Response samples

Content type
application/json
{
  • "status": true,
  • "first_admin_created": true
}

Setup time info

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
timezone
required
string
hour_pref
required
integer <int32>
date_format
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "timezone": "string",
  • "hour_pref": 0,
  • "date_format": "string"
}

Response samples

Content type
application/json
null

Update auto complete seconds

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Update date format

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Update time format

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Update timezone

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

Responses

Request samples

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

Response samples

Content type
application/json
null

User admin check

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get user details by id

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "UserID": 0,
  • "Fullname": "string",
  • "Username": "string",
  • "Email": "string",
  • "Hashed_PW": "string",
  • "Salt": "string",
  • "UseGravatar": true
}

Verify and reset password

Request Body schema: application/json
required
reset_code
required
string
email
required
string
new_password
required
string

Responses

Request samples

Content type
application/json
{
  • "reset_code": "string",
  • "email": "string",
  • "new_password": "string"
}

Response samples

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

Verify api key endpoint

Authorizations:
api_key

Responses

Response samples

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

Verify mfa and get key

Request Body schema: application/json
required
mfa_session_token
required
string
mfa_code
required
string

Responses

Request samples

Content type
application/json
{
  • "mfa_session_token": "string",
  • "mfa_code": "string"
}

Response samples

Content type
application/json
{
  • "status": "string",
  • "retrieved_key": "string",
  • "verified": true
}

podcasts

Podcast subscriptions, episodes, queue, and playback

Add podcast

Authorizations:
api_key
Request Body schema: application/json
required
required
object (PodcastValues)
podcast_index_id
integer or null <int64>

Responses

Request samples

Content type
application/json
{
  • "podcast_values": {
    },
  • "podcast_index_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "podcast_id": 0,
  • "first_episode_id": 0
}

Check episode in db

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
query Parameters
episode_title
required
string
episode_url
required
string

Responses

Response samples

Content type
application/json
{
  • "episode_in_db": true
}

Check podcast

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_name
required
string
podcast_url
required
string

Responses

Response samples

Content type
application/json
{
  • "exists": true
}

Clear all queue

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

Responses

Request samples

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

Response samples

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

Delete episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Download all podcast

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Download episode list

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "downloaded_episodes": [
    ]
}

Download podcast

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Download status

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Feeds that keep failing

The caller's podcasts whose last refresh failed (with the kind of error) and feeds a sync app subscribed to that couldn't be added.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "feeds": [
    ],
  • "imports": [
    ]
}

Dismiss a failed sync import

Forgets the failed import without unsubscribing: the feed stays subscribed in the sync apps.

Authorizations:
api_key
path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Unsubscribe from a feed that couldn't be added

Forgets the failed import and records an unsubscribe, so sync apps and the external sync server drop the feed too.

Authorizations:
api_key
path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Try adding a failed sync import again

Starts the import now (also after Pinepods stopped retrying). It shows in the activity panel.

Authorizations:
api_key
path Parameters
id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Refresh a failing podcast now

Refreshes one of the caller's podcasts straight away and returns its state afterwards: absent from feeds when it worked.

Authorizations:
api_key
path Parameters
podcast_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "feeds": [
    ],
  • "imports": [
    ]
}

Fetch podcast feed

Authorizations:
api_key
query Parameters
podcast_feed
required
string

Responses

Response samples

Content type
application/json
null

Fetch podcasting 2 data

Authorizations:
api_key
query Parameters
episode_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Fetch podcasting 2 pod data

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Fetch transcript

Authorizations:
api_key
Request Body schema: application/json
required
url
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Get auto-delete downloads days

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
integer or null <int32>

Responses

Request samples

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

Response samples

Content type
application/json
null

Get auto download status

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "auto_download": true
}

Get auto play next status

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "auto_play_next": true
}

Get auto queue status

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "auto_queue": true
}

Get default volume

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get episode id ep name

Authorizations:
api_key
query Parameters
episode_url
required
string
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get episode metadata

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
person_episode
boolean or null
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "person_episode": true,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Get extended stats

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get feed cutoff days

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

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

Get next playlist episode

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "episodetitle": "string",
  • "podcastname": "string",
  • "podcastid": 0,
  • "episodepubdate": "string",
  • "episodedescription": "string",
  • "episodeartwork": "string",
  • "episodeurl": "string",
  • "queueposition": 0,
  • "episodeduration": 0,
  • "queuedate": "string",
  • "listenduration": 0,
  • "episodeid": 0,
  • "completed": true,
  • "saved": true,
  • "queued": true,
  • "downloaded": true,
  • "is_youtube": true,
  • "is_video": true
}

Get next podcast episode

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "episodetitle": "string",
  • "podcastname": "string",
  • "podcastid": 0,
  • "episodepubdate": "string",
  • "episodedescription": "string",
  • "episodeartwork": "string",
  • "episodeurl": "string",
  • "queueposition": 0,
  • "episodeduration": 0,
  • "queuedate": "string",
  • "listenduration": 0,
  • "episodeid": 0,
  • "completed": true,
  • "saved": true,
  • "queued": true,
  • "downloaded": true,
  • "is_youtube": true,
  • "is_video": true
}

Get pinepods version

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Get play episode details

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "playback_speed": 0.1,
  • "start_skip": 0,
  • "end_skip": 0,
  • "playback_speed_customized": true
}

Get playback speed

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
integer or null <int32>

Responses

Request samples

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

Response samples

Content type
application/json
null

Get playlist episodes

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
playlist_id
required
integer <int32>
limit
integer or null <int64>
offset
integer or null <int64>

Responses

Response samples

Content type
application/json
null

Get playlists

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get podcast details

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get podcast details dynamic

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_title
required
string
podcast_url
required
string
podcast_index_id
required
integer <int32>
added
required
boolean
display_only
boolean or null

Responses

Response samples

Content type
application/json
{
  • "podcastid": 0,
  • "podcastname": "string",
  • "feedurl": "string",
  • "description": "string",
  • "author": "string",
  • "artworkurl": "string",
  • "explicit": true,
  • "episodecount": 0,
  • "categories": null,
  • "websiteurl": "string",
  • "podcastindexid": 0,
  • "is_youtube": true
}

Get podcast id

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_feed
required
string
podcast_title
required
string

Responses

Response samples

Content type
application/json
null

Get podcast id from ep id

Authorizations:
api_key
query Parameters
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Response samples

Content type
application/json
null

Get podcast id from ep name

Authorizations:
api_key
query Parameters
episode_name
required
string
episode_url
required
string
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get queued episodes

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get rss key

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_id
integer or null <int32>

Return a key that only covers this podcast's feed.

Responses

Response samples

Content type
application/json
null

Get stats

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get time info

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "timezone": "string",
  • "hour_pref": 0,
  • "date_format": "string"
}

Home overview

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Increment listen time

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Increment played

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Mark episode completed

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Mark episode uncompleted

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Get podcast favorite status

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "is_favorite": true
}

Get notification status

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "enabled": true
}

Get podcast download summary

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
sort_by
string or null
sort_order
string or null
filter
string or null
search
string or null

Responses

Response samples

Content type
application/json
{
  • "podcasts": [
    ]
}

Get podcast downloads paged

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
podcast_id
required
integer <int32>
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
sort_by
string or null
sort_order
string or null
filter
string or null
search
string or null

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ],
  • "total": 0
}

Podcast episodes

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_id
required
integer <int32>
limit
integer or null <int64>
offset
integer or null <int64>
sort_by
string or null
sort_order
string or null
search
string or null
filter
string or null

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ],
  • "total": 0
}

Get podpeople discover

Authorizations:
api_key
query Parameters
kind
required
string
limit
integer or null <int32>

Responses

Response samples

Content type
application/json
null

Proxy podcast categories

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Move an episode to the top of the queue

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
required
boolean
playing_episode_id
integer or null <int32>

Optional hint: the episode currently playing on the caller's device, so the server can insert the new episode directly under it ("play next"). When absent the episode is inserted at the top of the queue. Ignored by remove_queued_pod. The anchor may itself be a YouTube video, hence the companion playing_is_youtube flag for an unambiguous lookup.

playing_is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true,
  • "playing_episode_id": 0,
  • "playing_is_youtube": true
}

Response samples

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

Queue episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
required
boolean
playing_episode_id
integer or null <int32>

Optional hint: the episode currently playing on the caller's device, so the server can insert the new episode directly under it ("play next"). When absent the episode is inserted at the top of the queue. Ignored by remove_queued_pod. The anchor may itself be a YouTube video, hence the companion playing_is_youtube flag for an unambiguous lookup.

playing_is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true,
  • "playing_episode_id": 0,
  • "playing_is_youtube": true
}

Response samples

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

Personalized podcast recommendations

Authorizations:
api_key
query Parameters
refresh
boolean or null
limit
integer or null >= 0

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Record listen duration

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
listen_duration
required
number <double>
is_youtube
boolean
episode_duration
number or null <double>

The player's duration for the episode in seconds, if it knows it. Stored when the feed gave none (new episodes beyond the newest few are inserted with duration 0).

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "listen_duration": 0.1,
  • "is_youtube": true,
  • "episode_duration": 0
}

Response samples

Content type
application/json
null

Add history

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
episode_pos
required
number <float>
user_id
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "episode_pos": 0.1,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

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

Refresh a podcast's details from its feed

Reads the podcast's feed in full now, even if it looks unchanged, and updates its name, artwork, author, description, website and episodes. Details the user edited are kept unless reset_edits is set.

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
reset_edits
boolean

Also hand the details the user edited (name, artwork, ...) back to the feed.

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "reset_edits": true
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Remove podcast

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_name
required
string
podcast_url
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_name": "string",
  • "podcast_url": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

Remove podcast id

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

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true
}

Remove queued episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
required
boolean
playing_episode_id
integer or null <int32>

Optional hint: the episode currently playing on the caller's device, so the server can insert the new episode directly under it ("play next"). When absent the episode is inserted at the top of the queue. Ignored by remove_queued_pod. The anchor may itself be a YouTube video, hence the companion playing_is_youtube flag for an unambiguous lookup.

playing_is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true,
  • "playing_episode_id": 0,
  • "playing_is_youtube": true
}

Response samples

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

Remove saved episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

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

Remove youtube channel

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
channel_name
required
string
channel_url
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "channel_name": "string",
  • "channel_url": "string"
}

Response samples

Content type
application/json
null

Reorder queue

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
Request Body schema: application/json
required
Array of objects or null (ReorderQueueItem)

Preferred, type-aware ordering. Element 0 becomes queue position 1 (top).

episode_ids
Array of integers or null <int32> [ items <int32 > ]

Legacy id-only ordering, kept for backward compatibility with older clients. Used only when episodes is absent.

Responses

Request samples

Content type
application/json
{
  • "episodes": [
    ],
  • "episode_ids": [
    ]
}

Response samples

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

Return episodes

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
since
string or null

Responses

Response samples

Content type
application/json
{
  • "episodes": [
    ],
  • "total": 0
}

Return pods

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "pods": [
    ]
}

Return pods extra

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "pods": [
    ]
}

Save episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

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

Get saved episodes

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
sort_by
string or null
sort_order
string or null
filter
string or null
search
string or null

Responses

Response samples

Content type
application/json
{
  • "saved_episodes": [
    ],
  • "total": 0
}

Search data

Authorizations:
api_key
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
filter
string or null
Request Body schema: application/json
required
search_term
required
string
user_id
required
integer <int32>
categories
Array of strings or null

Responses

Request samples

Content type
application/json
{
  • "search_term": "string",
  • "user_id": 0,
  • "categories": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "total": 0
}

Stream episode

Authorizations:
api_key
path Parameters
episode_id
required
integer <int32>
query Parameters
api_key
required
string
user_id
required
integer <int32>
type
string or null

Responses

Update episode duration

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
new_duration
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "new_duration": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
null

Update feed cutoff days

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Update podcast info

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
feed_url
string or null
username
string or null
password
string or null
podcast_name
string or null
description
string or null
author
string or null
artwork_url
string or null
website_url
string or null
podcast_index_id
integer or null <int64>

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "feed_url": "string",
  • "username": "string",
  • "password": "string",
  • "podcast_name": "string",
  • "description": "string",
  • "author": "string",
  • "artwork_url": "string",
  • "website_url": "string",
  • "podcast_index_id": 0
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

User history

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
query Parameters
limit
integer or null <int64>
offset
integer or null <int64>
sort_by
string or null
sort_order
string or null
filter
string or null
search
string or null

Responses

Response samples

Content type
application/json
null

Youtube episodes

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
podcast_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Merge podcasts

Authorizations:
api_key
path Parameters
podcast_id
required
integer <int32>
Request Body schema: application/json
required
secondary_podcast_ids
required
Array of integers <int32> [ items <int32 > ]

Responses

Request samples

Content type
application/json
{
  • "secondary_podcast_ids": [
    ]
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

Get merged podcasts

Authorizations:
api_key
path Parameters
podcast_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "merged_podcast_ids": [
    ]
}

Unmerge podcast

Authorizations:
api_key
path Parameters
podcast_id
required
integer <int32>
target_podcast_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string"
}

people

Hosts and guests on podcasts and episodes, person pages, follows, and contributing to PodPeopleDB

Add people to a podcast or episode

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
episode_id
integer or null <int32>

Credit these people on one episode instead of the whole show.

required
Array of objects (ContributePerson)

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "episode_id": 0,
  • "people": [
    ]
}

Response samples

Content type
application/json
[
  • {
    }
]

People on an episode

Authorizations:
api_key
path Parameters
episode_id
required
integer <int32>

Your episode id

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Followed people

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Find a person id

Authorizations:
api_key
query Parameters
podpeople_id
integer or null <int64>

A PodPeopleDB person id (from search results).

name
string or null

Or a name.

Responses

Response samples

Content type
application/json
null

People on a podcast

Authorizations:
api_key
path Parameters
podcast_id
required
integer <int32>

Your podcast id

Responses

Response samples

Content type
application/json
{
  • "people": [
    ],
  • "guests": [
    ]
}

Search people

Authorizations:
api_key
query Parameters
q
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Person profile

Authorizations:
api_key
path Parameters
person_id
required
integer <int32>

PinePods person id

query Parameters
limit
integer or null <int64>

Library episodes per page (default 50, max 200).

offset
integer or null <int64>

Responses

Response samples

Content type
application/json
{
  • "person": {
    },
  • "podcasts": [
    ],
  • "episodes": [
    ],
  • "external_episodes": [
    ],
  • "refreshing": true
}

Follow a person

Authorizations:
api_key
path Parameters
person_id
required
integer <int32>

PinePods person id

Responses

Response samples

Content type
application/json
null

Unfollow a person

Authorizations:
api_key
path Parameters
person_id
required
integer <int32>

PinePods person id

Responses

Response samples

Content type
application/json
null

episodes

Episode actions: download, save, share, bulk ops

Bulk delete downloaded episodes

Authorizations:
api_key
Request Body schema: application/json
required
episode_ids
required
Array of integers <int32> [ items <int32 > ]
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_ids": [
    ],
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "processed_count": 0,
  • "failed_count": 0
}

Bulk download episodes

Authorizations:
api_key
Request Body schema: application/json
required
episode_ids
required
Array of integers <int32> [ items <int32 > ]
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_ids": [
    ],
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "processed_count": 0,
  • "failed_count": 0
}

Bulk mark episodes completed

Authorizations:
api_key
Request Body schema: application/json
required
episode_ids
required
Array of integers <int32> [ items <int32 > ]
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_ids": [
    ],
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "processed_count": 0,
  • "failed_count": 0
}

Bulk queue episodes

Authorizations:
api_key
Request Body schema: application/json
required
episode_ids
required
Array of integers <int32> [ items <int32 > ]
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_ids": [
    ],
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "processed_count": 0,
  • "failed_count": 0
}

Bulk save episodes

Authorizations:
api_key
Request Body schema: application/json
required
episode_ids
required
Array of integers <int32> [ items <int32 > ]
user_id
required
integer <int32>
is_youtube
boolean or null

Responses

Request samples

Content type
application/json
{
  • "episode_ids": [
    ],
  • "user_id": 0,
  • "is_youtube": true
}

Response samples

Content type
application/json
{
  • "message": "string",
  • "processed_count": 0,
  • "failed_count": 0
}

Get episode by url key

path Parameters
url_key
required
string

Responses

Response samples

Content type
application/json
null

Share episode

Authorizations:
api_key
path Parameters
episode_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

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>

Minimum episode length in minutes (stored, and returned by get_playlists, in seconds).

max_duration
integer or null <int32>

Maximum episode length in minutes (stored, and returned by get_playlists, in seconds).

sort_order
required
string

One of date_asc, date_desc, duration_asc, duration_desc, listen_progress, completion.

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": "date_desc",
  • "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>

Minimum episode length in minutes (stored, and returned by get_playlists, in seconds).

max_duration
integer or null <int32>

Maximum episode length in minutes (stored, and returned by get_playlists, in seconds).

sort_order
required
string

One of date_asc, date_desc, duration_asc, duration_desc, listen_progress, completion.

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": "date_desc",
  • "group_by_podcast": true,
  • "max_episodes": 0,
  • "icon_name": "string"
}

Response samples

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

settings

User and server settings

Add category

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
category
required
string

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "category": "string"
}

Response samples

Content type
application/json
null

Add custom podcast

Authorizations:
api_key
Request Body schema: application/json
required
feed_url
required
string
user_id
required
integer <int32>
username
string or null
password
string or null
youtube_channel
boolean or null
feed_cutoff
integer or null <int32>

Responses

Request samples

Content type
application/json
{
  • "feed_url": "string",
  • "user_id": 0,
  • "username": "string",
  • "password": "string",
  • "youtube_channel": true,
  • "feed_cutoff": 0
}

Response samples

Content type
application/json
null

Add gpodder server

Authorizations:
api_key
Request Body schema: application/json
required
gpodder_url
required
string
gpodder_username
required
string
gpodder_password
required
string

Responses

Request samples

Content type
application/json
{
  • "gpodder_url": "string",
  • "gpodder_username": "string",
  • "gpodder_password": "string"
}

Response samples

Content type
application/json
null

Add login user

Authorizations:
api_key
Request Body schema: application/json
required
fullname
required
string
username
required
string
email
required
string
hash_pw
required
string

Responses

Request samples

Content type
application/json
{
  • "fullname": "string",
  • "username": "string",
  • "email": "string",
  • "hash_pw": "string"
}

Response samples

Content type
application/json
null

Add nextcloud server

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
token
required
string
poll_endpoint
required
string
nextcloud_url
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "token": "string",
  • "poll_endpoint": "string",
  • "nextcloud_url": "string"
}

Response samples

Content type
application/json
null

Add oidc provider

Authorizations:
api_key
Request Body schema: application/json
required
provider_name
required
string
client_id
required
string
client_secret
required
string
authorization_url
required
string
token_url
required
string
user_info_url
required
string
button_text
required
string
scope
required
string
button_color
required
string
button_text_color
required
string
icon_svg
string or null
name_claim
string or null
email_claim
string or null
username_claim
string or null
roles_claim
string or null
user_role
string or null
admin_role
string or null

Responses

Request samples

Content type
application/json
{
  • "provider_name": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "authorization_url": "string",
  • "token_url": "string",
  • "user_info_url": "string",
  • "button_text": "string",
  • "scope": "string",
  • "button_color": "string",
  • "button_text_color": "string",
  • "icon_svg": "string",
  • "name_claim": "string",
  • "email_claim": "string",
  • "username_claim": "string",
  • "roles_claim": "string",
  • "user_role": "string",
  • "admin_role": "string"
}

Response samples

Content type
application/json
null

Add user

Authorizations:
api_key
Request Body schema: application/json
required
fullname
required
string
username
required
string
email
required
string
hash_pw
required
string

Responses

Request samples

Content type
application/json
{
  • "fullname": "string",
  • "username": "string",
  • "email": "string",
  • "hash_pw": "string"
}

Response samples

Content type
application/json
null

Confirm or deny a detected ad segment (per-user)

Authorizations:
api_key
Request Body schema: application/json
required
segment_id
required
integer <int32>
user_id
required
integer <int32>
status
required
string

Responses

Request samples

Content type
application/json
{
  • "segment_id": 0,
  • "user_id": 0,
  • "status": "string"
}

Response samples

Content type
application/json
null

Set per-podcast ad-skip auto-activate

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "enabled": true
}

Response samples

Content type
application/json
null

Set per-podcast auto-ad-detect

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "enabled": true
}

Response samples

Content type
application/json
null

Set per-podcast auto-transcribe

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
enabled
boolean

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "enabled": true
}

Response samples

Content type
application/json
null

Set per-podcast silence-trim (enable + threshold)

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
enabled
boolean
threshold
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "enabled": true,
  • "threshold": 0
}

Response samples

Content type
application/json
null

Adjust skip times

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
start_skip
integer <int32>
end_skip
integer <int32>
user_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "start_skip": 0,
  • "end_skip": 0,
  • "user_id": 0
}

Response samples

Content type
application/json
null

Self service status

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

List models installed in the AI sidecar (admin)

Authorizations:
api_key
query Parameters
remote_url
string or null

Responses

Response samples

Content type
application/json
null

Pull a model into the AI sidecar (admin)

Authorizations:
api_key
Request Body schema: application/json
required
kind
required
string
model
required
string
repo
string or null
filename
string or null
url
string or null

Responses

Request samples

Content type
application/json
{
  • "kind": "string",
  • "model": "string",
  • "repo": "string",
  • "filename": "string",
  • "url": "string"
}

Response samples

Content type
application/json
null

Get global AI settings (admin)

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Update global AI settings (admin)

Authorizations:
api_key
Request Body schema: application/json
required
transcription_model
required
string
llm_backend
required
string
llm_model
string or null
llm_url
string or null
llm_api_key
string or null
clear_api_key
boolean
whisper_device
string or null
whisper_compute_type
string or null

Responses

Request samples

Content type
application/json
{
  • "transcription_model": "string",
  • "llm_backend": "string",
  • "llm_model": "string",
  • "llm_url": "string",
  • "llm_api_key": "string",
  • "clear_api_key": true,
  • "whisper_device": "string",
  • "whisper_compute_type": "string"
}

Response samples

Content type
application/json
null

Whether the optional AI sidecar is available

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Backup server

Authorizations:
api_key
Request Body schema: application/json
required
database_pass
required
string

Responses

Request samples

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

Backup user

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

Responses

Request samples

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

Check gpodder settings

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Check mfa enabled

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Clear podcast auto-delete downloads days

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Clear podcast playback speed

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Create api key

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
rssonly
required
boolean
podcast_ids
Array of integers or null <int32> [ items <int32 > ]

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "rssonly": true,
  • "podcast_ids": [
    ]
}

Response samples

Content type
application/json
null

Delete api key

Authorizations:
api_key
Request Body schema: application/json
required
api_id
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Delete backup file

Authorizations:
api_key
Request Body schema: application/json
required
backup_filename
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Delete mfa

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Detect ads for an episode (AI sidecar)

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
force
boolean
download_first
boolean

Download the episode to the server first (when it isn't) and detect ads on that copy, so ad times match what the user plays.

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "force": true,
  • "download_first": true
}

Response samples

Content type
application/json
null

Run silence detection for an episode

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
force
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "force": true
}

Response samples

Content type
application/json
null

Get download metadata settings

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "folder_cover": true,
  • "episode_cover": true,
  • "metadata_sidecar": true,
  • "metadata_format": "string",
  • "metadata_subfolder": true
}

Set download metadata settings

Authorizations:
api_key
Request Body schema: application/json
required
folder_cover
required
boolean
episode_cover
required
boolean
metadata_sidecar
required
boolean
metadata_format
required
string
metadata_subfolder
required
boolean

Responses

Request samples

Content type
application/json
{
  • "folder_cover": true,
  • "episode_cover": true,
  • "metadata_sidecar": true,
  • "metadata_format": "string",
  • "metadata_subfolder": true
}

Response samples

Content type
application/json
null

Download status

Authorizations:
api_key

Responses

Enable auto download

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
auto_download
required
boolean
user_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "auto_download": true,
  • "user_id": 0
}

Response samples

Content type
application/json
null

Enable auto play next

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
auto_play_next
required
boolean
user_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "auto_play_next": true,
  • "user_id": 0
}

Response samples

Content type
application/json
null

Enable auto queue

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
auto_queue
required
boolean
user_id
required
integer <int32>

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "auto_queue": true,
  • "user_id": 0
}

Response samples

Content type
application/json
null

Enable disable downloads

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Enable disable self service

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Get auto-skip segments for an episode

Authorizations:
api_key
query Parameters
episode_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get the stored (generated) transcript for an episode

Authorizations:
api_key
query Parameters
episode_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Generate mfa secret

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get per-podcast ad-skip auto-activate setting

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get api info

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get per-podcast auto-ad-detect setting

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get delete-downloads-when-finished

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
integer or null <int32>

Responses

Request samples

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

Response samples

Content type
application/json
null

Get per-podcast auto-transcribe setting

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get available languages

Responses

Response samples

Content type
application/json
{
  • "languages": [
    ]
}

Get email settings

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "Emailsettingsid": 0,
  • "ServerName": "string",
  • "ServerPort": 0,
  • "FromEmail": "string",
  • "SendMode": "string",
  • "Encryption": "string",
  • "AuthRequired": 0,
  • "Username": "string",
  • "Password": "string"
}

Get gpodder settings

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get ignored podcasts

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get scheduled backup

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get server default language

Responses

Response samples

Content type
application/json
null

Get per-podcast silence-trim settings

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get unmatched podcasts

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get user info

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get user language

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

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

Ignore podcast index id

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
ignore
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "ignore": true
}

Response samples

Content type
application/json
null

Initiate nextcloud login

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

Responses

Request samples

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

Response samples

Content type
application/json
null

List backup files

Authorizations:
api_key
Request Body schema: application/json
required
object (ListBackupFilesRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

List oidc providers

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Manual backup to directory

Authorizations:
api_key
Request Body schema: application/json
required
object (ManualBackupRequest)

Responses

Request samples

Content type
application/json
{ }

Response samples

Content type
application/json
null

Get my user info

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Discover oidc provider endpoints

Authorizations:
api_key
Request Body schema: application/json
required
url
required
string

Issuer URL or full .well-known/openid-configuration URL

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "issuer": "string",
  • "authorization_endpoint": "string",
  • "token_endpoint": "string",
  • "userinfo_endpoint": "string",
  • "scopes_supported": [
    ],
  • "claims_supported": [
    ]
}

Clear podcast cover preference

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set or clear a podcast's delete-downloads-when-finished

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
enabled
boolean or null

null goes back to the user's default.

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "enabled": true
}

Response samples

Content type
application/json
null

Set podcast auto-delete downloads days

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set podcast cover preference

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
use_podcast_covers
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "use_podcast_covers": true
}

Response samples

Content type
application/json
null

Set podcast playback speed

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
playback_speed
required
number <double>

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "playback_speed": 0.1
}

Response samples

Content type
application/json
null

Toggle podcast favorite

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
is_favorite
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "is_favorite": true
}

Response samples

Content type
application/json
null

Toggle podcast notifications

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
podcast_id
required
integer <int32>
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "podcast_id": 0,
  • "enabled": true
}

Response samples

Content type
application/json
null

Remove category

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
category
required
string

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "category": "string"
}

Response samples

Content type
application/json
null

Remove oidc provider

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

Responses

Request samples

Content type
application/json
0
0

Response samples

Content type
application/json
null

Remove podcast sync

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Restore from backup file

Authorizations:
api_key
Request Body schema: application/json
required
backup_filename
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Restore server

Authorizations:
api_key
Request Body schema: multipart/form-data
required

Uploaded file

string

Responses

Response samples

Content type
application/json
null

Restore status

Responses

Response samples

Content type
application/json
null

Rss feed status

Authorizations:
api_key

Responses

Get user rss key

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Save email settings

Authorizations:
api_key
Request Body schema: application/json
required
required
object (EmailSettings)
server_name
required
string
server_port
required
string
from_email
required
string
send_mode
required
string
encryption
required
string
auth_required
required
boolean
email_username
required
string
email_password
required
string

Responses

Request samples

Content type
application/json
{
  • "email_settings": {
    }
}

Response samples

Content type
application/json
null

Save mfa secret

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Schedule backup

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
cron_schedule
required
string
enabled
required
boolean
retention_count
integer or null <int32>

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "cron_schedule": "string",
  • "enabled": true,
  • "retention_count": 0
}

Response samples

Content type
application/json
null

Send email

Authorizations:
api_key
Request Body schema: application/json
required
to_email
required
string
subject
required
string
message
required
string

Responses

Request samples

Content type
application/json
{
  • "to_email": "string",
  • "subject": "string",
  • "message": "string"
}

Response samples

Content type
application/json
null

Send test email

Authorizations:
api_key
Request Body schema: application/json
required
server_name
required
string
server_port
required
string
from_email
required
string
encryption
required
string
auth_required
required
boolean
email_username
required
string
email_password
required
string
to_email
required
string
message
required
string

Responses

Request samples

Content type
application/json
{
  • "server_name": "string",
  • "server_port": "string",
  • "from_email": "string",
  • "encryption": "string",
  • "auth_required": true,
  • "email_username": "string",
  • "email_password": "string",
  • "to_email": "string",
  • "message": "string"
}

Response samples

Content type
application/json
null

Set fullname

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Set password

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
Request Body schema: application/json
required
hash_pw
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Get startpage

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Update startpage

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
startpage
string or null

Responses

Response samples

Content type
application/json
null

Toggle rss feeds

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Transcribe an episode (AI sidecar)

Authorizations:
api_key
Request Body schema: application/json
required
episode_id
required
integer <int32>
user_id
required
integer <int32>
force
boolean

Responses

Request samples

Content type
application/json
{
  • "episode_id": 0,
  • "user_id": 0,
  • "force": true
}

Response samples

Content type
application/json
null

Update oidc provider

Authorizations:
api_key
path Parameters
provider_id
required
integer <int32>
Request Body schema: application/json
required
provider_name
required
string
client_id
required
string
client_secret
required
string
authorization_url
required
string
token_url
required
string
user_info_url
required
string
button_text
required
string
scope
required
string
button_color
required
string
button_text_color
required
string
icon_svg
string or null
name_claim
string or null
email_claim
string or null
username_claim
string or null
roles_claim
string or null
user_role
string or null
admin_role
string or null

Responses

Request samples

Content type
application/json
{
  • "provider_name": "string",
  • "client_id": "string",
  • "client_secret": "string",
  • "authorization_url": "string",
  • "token_url": "string",
  • "user_info_url": "string",
  • "button_text": "string",
  • "scope": "string",
  • "button_color": "string",
  • "button_text_color": "string",
  • "icon_svg": "string",
  • "name_claim": "string",
  • "email_claim": "string",
  • "username_claim": "string",
  • "roles_claim": "string",
  • "user_role": "string",
  • "admin_role": "string"
}

Response samples

Content type
application/json
null

Update podcast index id

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Search service and Podping status

Admin only. Checks that the search service answers and reports Podping: whether it's on, the relay's state and what this server did with its announcements.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "search": {
    },
  • "podping": {
    }
}

Turn Podping on or off

Admin only. When on, Pinepods reads which feeds Podping announced from the relay and refreshes the ones it has right away. Only announcements are fetched; what this server subscribes to is never sent.

Authorizations:
api_key
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "search": {
    },
  • "podping": {
    }
}

Update user language

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Create custom theme

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
name
required
string
background_color
required
string
button_color
required
string
container_button_color
required
string
button_text_color
required
string
text_color
required
string
text_secondary_color
required
string
border_color
required
string
accent_color
required
string
prog_bar_color
required
string
error_color
required
string
bonus_color
required
string
secondary_background
required
string
container_background
required
string
standout_color
required
string
hover_color
required
string
link_color
required
string
thumb_color
required
string
unfilled_color
required
string
check_box_color
required
string

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "name": "string",
  • "background_color": "string",
  • "button_color": "string",
  • "container_button_color": "string",
  • "button_text_color": "string",
  • "text_color": "string",
  • "text_secondary_color": "string",
  • "border_color": "string",
  • "accent_color": "string",
  • "prog_bar_color": "string",
  • "error_color": "string",
  • "bonus_color": "string",
  • "secondary_background": "string",
  • "container_background": "string",
  • "standout_color": "string",
  • "hover_color": "string",
  • "link_color": "string",
  • "thumb_color": "string",
  • "unfilled_color": "string",
  • "check_box_color": "string"
}

Response samples

Content type
application/json
null

Delete custom theme

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get custom themes

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Delete user

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Final admin

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Get global podcast cover preference

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Get notification settings

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Update notification settings

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
platform
required
string
enabled
required
boolean
ntfy_topic
string or null
ntfy_server_url
string or null
ntfy_username
string or null
ntfy_password
string or null
ntfy_access_token
string or null
gotify_url
string or null
gotify_token
string or null
http_url
string or null
http_token
string or null
http_method
string or null

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "platform": "string",
  • "enabled": true,
  • "ntfy_topic": "string",
  • "ntfy_server_url": "string",
  • "ntfy_username": "string",
  • "ntfy_password": "string",
  • "ntfy_access_token": "string",
  • "gotify_url": "string",
  • "gotify_token": "string",
  • "http_url": "string",
  • "http_token": "string",
  • "http_method": "string"
}

Response samples

Content type
application/json
null

Set delete-downloads-when-finished (user default)

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set auto-delete downloads days (user default)

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set default volume (user default)

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set email

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set global podcast cover preference

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
use_podcast_covers
required
boolean
podcast_id
integer or null <int32>

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "use_podcast_covers": true,
  • "podcast_id": 0
}

Response samples

Content type
application/json
null

Set isadmin

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set playback speed user

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
playback_speed
required
number <double>

Responses

Request samples

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

Response samples

Content type
application/json
null

Set theme

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set whether the user's Gravatar is shown

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Set username

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Test notification

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Verify gpodder auth

Authorizations:
api_key
Request Body schema: application/json
required
gpodder_url
required
string
gpodder_username
required
string
gpodder_password
required
string

Responses

Request samples

Content type
application/json
{
  • "gpodder_url": "string",
  • "gpodder_username": "string",
  • "gpodder_password": "string"
}

Response samples

Content type
application/json
null

Verify mfa

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Verify temp mfa

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Get yt-dlp management settings + current version (admin)

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Update yt-dlp management settings (admin)

Authorizations:
api_key
Request Body schema: application/json
required
auto_update
required
boolean
channel
required
string

Responses

Request samples

Content type
application/json
{
  • "auto_update": true,
  • "channel": "string"
}

Response samples

Content type
application/json
null

Trigger an immediate yt-dlp self-update (admin)

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

sync

gpodder / Nextcloud synchronization

Gpodder status

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Gpodder toggle

Authorizations:
api_key
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
null

Gpodder get default device

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Gpodder get all devices

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Gpodder create device

Authorizations:
api_key
Request Body schema: application/json
required
device_name
required
string
device_type
required
string
device_caption
string or null

Responses

Request samples

Content type
application/json
{
  • "device_name": "string",
  • "device_type": "string",
  • "device_caption": "string"
}

Response samples

Content type
application/json
null

Gpodder get user devices

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Gpodder get statistics

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "server_url": "string",
  • "sync_type": "string",
  • "sync_enabled": true,
  • "server_devices": [
    ],
  • "total_devices": 0,
  • "server_subscriptions": [
    ],
  • "total_subscriptions": 0,
  • "recent_episode_actions": [
    ],
  • "total_episode_actions": 0,
  • "connection_status": "string",
  • "last_sync_timestamp": "string",
  • "api_endpoints_tested": [
    ]
}

Gpodder set default (no longer has an effect)

Authorizations:
api_key
path Parameters
device_id
required
string

Responses

Response samples

Content type
application/json
null

Gpodder sync

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Gpodder force sync

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Gpodder test connection

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Devices on the PinePods gpodder server

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Rename a device

Authorizations:
api_key
path Parameters
device_id
required
integer <int32>
Request Body schema: application/json
required
caption
required
string

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "success": true
}

Remove a device

Removes an app's device. Its history stays; the app gets a new device the next time it syncs.

Authorizations:
api_key
path Parameters
device_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Dismiss the sync settings notice

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Sync with the external server now

Authorizations:
api_key
query Parameters
full
boolean or null

Full sync: pull everything again and send the whole library and listening state.

Responses

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "summary": {
    },
  • "target": {
    }
}

PinePods gpodder server settings

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "enabled": true,
  • "username": "string",
  • "server_url": "string",
  • "server_url_configured": true,
  • "notice": "string"
}

Turn the PinePods gpodder server on or off

Authorizations:
api_key
Request Body schema: application/json
required
enabled
required
boolean

Responses

Request samples

Content type
application/json
{
  • "enabled": true
}

Response samples

Content type
application/json
{
  • "enabled": true,
  • "username": "string",
  • "server_url": "string",
  • "server_url_configured": true,
  • "notice": "string"
}

List app passwords

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create an app password

Creates a password for a gpodder app. The password is in this response only.

Authorizations:
api_key
Request Body schema: application/json
required
label
string or null

What it's for, e.g. "AntennaPod on my phone".

Responses

Request samples

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

Response samples

Content type
application/json
{
  • "id": 0,
  • "label": "string",
  • "password": "string"
}

Revoke an app password

Authorizations:
api_key
path Parameters
app_password_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Sync statistics

Read from the sync log; no server is contacted.

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "server_enabled": true,
  • "subscriptions": 0,
  • "devices": 0,
  • "total_episode_actions": 0,
  • "last_change": 0,
  • "recent_episode_actions": [
    ],
  • "target": {
    }
}

External sync server and its status

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "target": {
    }
}

Set up the external sync server

Authorizations:
api_key
Request Body schema: application/json
required
kind
required
string

gpodder or nextcloud.

url
required
string
username
required
string
password
string or null

Leave out to reuse the stored password of the same server and account.

device_name
string or null

gpodder only: the device Pinepods syncs as. Left out: keep the current one, or pick one.

Responses

Request samples

Content type
application/json
{
  • "kind": "string",
  • "url": "string",
  • "username": "string",
  • "password": "string",
  • "device_name": "string"
}

Response samples

Content type
application/json
{
  • "target": {
    },
  • "task_id": "string"
}

Remove the external sync server

Authorizations:
api_key

Responses

Response samples

Content type
application/json
{
  • "success": true
}

Test an external sync server

Signs in with the given credentials (gpodder: and lists the devices) without saving anything or creating a device.

Authorizations:
api_key
Request Body schema: application/json
required
kind
required
string

gpodder or nextcloud.

url
required
string
username
required
string
password
string or null

Leave out to reuse the stored password of the same server and account.

device_name
string or null

gpodder only: the device Pinepods syncs as. Left out: keep the current one, or pick one.

Responses

Request samples

Content type
application/json
{
  • "kind": "string",
  • "url": "string",
  • "username": "string",
  • "password": "string",
  • "device_name": "string"
}

Response samples

Content type
application/json
{
  • "success": true,
  • "message": "string",
  • "devices": [
    ],
  • "device_name": "string"
}

tasks

Background tasks and progress

Auto complete episodes

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Cleanup tasks

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Refresh gpodder subscriptions

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Refresh hosts

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Refresh Nextcloud subscriptions

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Refresh all podcasts

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Update playlists

Authorizations:
api_key

Responses

Response samples

Content type
application/json
null

Startup tasks

Request Body schema: application/json
required
api_key
required
string

Responses

Request samples

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

Response samples

Content type
application/json
null

Get active tasks

Authorizations:
api_key

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get user tasks

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get task status

Authorizations:
api_key
path Parameters
task_id
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "task_type": "string",
  • "user_id": 0,
  • "status": "PENDING",
  • "progress": 0.1,
  • "message": "string",
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z",
  • "result": null,
  • "episode_title": "string",
  • "podcast_name": "string",
  • "completed_at": "2019-08-24T14:15:22Z",
  • "art_url": "string",
  • "detail": "string",
  • "group": "string",
  • "group_label": "string",
  • "total": 0
}

notifications

Durable in-app notifications (Activity center)

List the user's live durable notifications (messages/alerts). Expired ones are dropped server-side. Powers the Activity center on load and as a WS fallback.

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Clear all (or all read) notifications for the user.

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
read_only
boolean

When true, only already-read notifications are removed.

Responses

Dismiss (delete) one notification.

Authorizations:
api_key
path Parameters
id
required
string
query Parameters
user_id
required
integer <int32>

Responses

Mark one notification read.

Authorizations:
api_key
path Parameters
id
required
string
query Parameters
user_id
required
integer <int32>

Responses

feed

Public RSS feed generation

Get user feed

path Parameters
user_id
required
integer <int32>
query Parameters
api_key
required
string
limit
integer or null <int32>
podcast_id
integer or null <int32>
type
string or null
source
string or null

Which collection to build the feed from. Absent = all subscriptions (default). One of: saved, queue, playlist, collection, downloads, history.

id
integer or null <int32>

Playlist or collection id (required when source is playlist or collection).

Responses

proxy

Media and image proxying

Proxy image

query Parameters
url
required
string

Responses

local

Local podcasts and media

Add local podcast

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
directory_path
required
string
podcast_name
required
string
description
string or null
author
string or null
explicit
boolean or null

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "directory_path": "string",
  • "podcast_name": "string",
  • "description": "string",
  • "author": "string",
  • "explicit": true
}

Response samples

Content type
application/json
null

Add local podcast artwork

Authorizations:
api_key
Request Body schema: multipart/form-data
required

Uploaded file

string

Responses

Response samples

Content type
application/json
null

Detect local cover

Authorizations:
api_key
query Parameters
path
string

Responses

Response samples

Content type
application/json
null

List local directories

Authorizations:
api_key
query Parameters
path
string

Responses

Response samples

Content type
application/json
null

Refresh local podcast

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

Responses

Request samples

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

Response samples

Content type
application/json
null

youtube

YouTube channel integration

Check youtube channel

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>
channel_name
required
string
channel_url
required
string

Responses

Response samples

Content type
application/json
null

Search youtube channels

Authorizations:
api_key
query Parameters
query
required
string
max_results
integer or null <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
null

Set a channel's video filter

Authorizations:
api_key
Request Body schema: application/json
required
podcast_id
required
integer <int32>
user_id
required
integer <int32>
min_minutes
integer or null <int32>

Shortest video to add, in minutes; empty or 0 for no limit.

max_minutes
integer or null <int32>

Longest video to add, in minutes; empty or 0 for no limit.

title_contains
string or null

Only add videos whose title contains this (any case); empty for all.

Responses

Request samples

Content type
application/json
{
  • "podcast_id": 0,
  • "user_id": 0,
  • "min_minutes": 0,
  • "max_minutes": 0,
  • "title_contains": "string"
}

Response samples

Content type
application/json
{
  • "min_minutes": 0,
  • "max_minutes": 0,
  • "title_contains": "string"
}

Subscribe to youtube channel

Authorizations:
api_key
query Parameters
channel_id
required
string
user_id
required
integer <int32>
feed_cutoff
integer or null <int32>

Responses

Response samples

Content type
application/json
null

Get a channel's video filter

Authorizations:
api_key
query Parameters
podcast_id
required
integer <int32>
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "min_minutes": 0,
  • "max_minutes": 0,
  • "title_contains": "string"
}

collections

Get the collection add-UI preference

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

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

Set the collection add-UI preference

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

Responses

Request samples

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

Response samples

Content type
application/json
null

Add multiple episodes to a collection

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
collection_id
required
integer <int32>
required
Array of items

Each entry is (episode_id, is_youtube)

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "collection_id": 0,
  • "episodes": [
    ]
}

Response samples

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

List the distinct podcast categories across a user's subscriptions

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "categories": [
    ]
}

Create a collection

Authorizations:
api_key
Request Body schema: application/json
required
user_id
required
integer <int32>
name
required
string
description
string or null
icon
string or null
auto_add_categories
Array of strings or null

Podcast categories to auto-add episodes from (None/empty = disabled).

backfill
boolean or null

When true, immediately backfill existing matching episodes after saving.

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "name": "string",
  • "description": "string",
  • "icon": "string",
  • "auto_add_categories": [
    ],
  • "backfill": true
}

Response samples

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

List a user's collections

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "collections": [
    ]
}

Delete a collection

Authorizations:
api_key
path Parameters
collection_id
required
integer <int32>

Responses

Response samples

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

Update a collection

Authorizations:
api_key
path Parameters
collection_id
required
integer <int32>
Request Body schema: application/json
required
name
string or null
description
string or null
icon
string or null
auto_add_categories
Array of strings or null

Podcast categories to auto-add episodes from (empty vec clears the rule).

backfill
boolean or null

When true, immediately backfill existing matching episodes after saving.

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "description": "string",
  • "icon": "string",
  • "auto_add_categories": [
    ],
  • "backfill": true
}

Response samples

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

Add an episode to a collection

Authorizations:
api_key
path Parameters
collection_id
required
integer <int32>
Request Body schema: application/json
required
user_id
required
integer <int32>
episode_id
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "episode_id": 0,
  • "is_youtube": true
}

Response samples

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

Get a collection's episodes (paginated)

Authorizations:
api_key
path Parameters
collection_id
required
integer <int32>
query Parameters
limit
required
integer <int64>
offset
required
integer <int64>
sort_by
required
string
sort_order
required
string
filter
required
string

Responses

Response samples

Content type
application/json
{
  • "saved_episodes": [
    ],
  • "total": 0
}

Remove an episode from a collection

Authorizations:
api_key
path Parameters
collection_id
required
integer <int32>
Request Body schema: application/json
required
user_id
required
integer <int32>
episode_id
required
integer <int32>
is_youtube
required
boolean

Responses

Request samples

Content type
application/json
{
  • "user_id": 0,
  • "episode_id": 0,
  • "is_youtube": true
}

Response samples

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

Which collections contain this episode

Authorizations:
api_key
path Parameters
user_id
required
integer <int32>
episode_id
required
integer <int32>
query Parameters
is_youtube
required
boolean

Responses

Response samples

Content type
application/json
{
  • "collection_ids": [
    ]
}

nowplaying

List the user's active devices and what each is currently playing. Backed by ephemeral Valkey snapshots with a TTL, so a device that stops reporting drops off automatically. Powers the "see / control my other devices" UI for clients that aren't holding a live socket.

Authorizations:
api_key
query Parameters
user_id
required
integer <int32>

Responses

Response samples

Content type
application/json
{
  • "devices": [
    ]
}