3 description: "gpodder.net APIs"
5 title: "gpodder.net APIs"
7 url: "https://gpoddernet.readthedocs.io/en/latest/api/"
9 name: "GNU Affero General Public License v3.0"
10 url: "https://github.com/podStation/mygpo/blob/master/COPYING"
12 - url: https://gpodder.net
13 description: "Client parametrization server"
15 - name: "Client Parametrization"
17 description: "Find out more"
18 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/clientconfig.html"
19 - name: "Authentication"
21 description: "Find out more"
22 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/auth.html"
25 description: "Find out more"
26 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/directory.html"
29 description: "Find out more"
30 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/suggestions.html"
33 description: "Find out more"
34 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/suggestions.html"
35 - name: "Device Synchronization"
37 description: "Find out more"
38 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/sync.html"
39 - name: "Subscriptions"
41 description: "Find out more"
42 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/subscriptions.html"
43 - name: "Episode Actions"
45 description: "Find out more"
46 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/events.html"
49 description: "Find out more"
50 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/settings.html"
51 - name: "Podcast Lists"
53 description: "Find out more"
54 url: "https://gpoddernet.readthedocs.io/en/latest/api/reference/podcastlists.html"
59 - "Client Parametrization"
60 summary: "Retrieves client parametrization"
62 operationId: "getClientParametrization"
69 $ref: "#/components/schemas/ClientConfiguration"
70 /api/2/auth/{username}/login.json:
74 summary: Log in the given user for the given device via HTTP Basic Auth.
78 description: "Username to login"
88 description: "Unauthorized"
90 description: "Cookies have different username then the one provided"
91 /api/2/auth/{username}/logout.json:
95 summary: "Log out user"
96 description: "Log out the given user. Removes the session ID from the database."
100 description: "Username to login"
110 description: "if the client provides a cookie, but for a different username than the one given"
111 /api/2/tags/{count}.json:
115 summary: "Retrieve Top Tags"
119 description: "number of tags to return"
130 /api/2/tag/{tag}/{count}.json:
134 summary: "Retrieve Podcasts for Tag"
138 description: "maximum number of podcasts to return"
144 description: "URL-encoded tag"
155 /api/2/data/podcast.json:
159 summary: "Retrieve Podcast Data"
160 description: "Returns information for the podcast with the given URL or 404 if there is no podcast with this URL."
164 description: "the feed URL of the podcast"
175 /api/2/data/episode.json:
179 summary: "Retrieve Episode Data"
180 description: "Returns information for the episode with the given {episode-url} that belongs to the podcast with the {podcast-url}"
182 - name: "podcast-url"
184 description: "feed URL of the podcast to which the episode belongs"
188 - name: "episode-url"
190 description: "media URL of the episode"
201 /toplist/{number}.{format}:
205 summary: "Podcast Toplist"
209 description: "maximum number of podcasts to return"
215 description: "Format of the response"
218 $ref: "#/components/schemas/Format"
221 description: "a function name on which the response is wrapped (only valid for format jsonp; since 2.8)"
226 description: "returns logo URLs to scaled images"
252 summary: "Podcast Toplist"
256 description: "Format of the response"
259 $ref: "#/components/schemas/Format"
262 description: "search query"
268 description: "a functionname on which the response is wrapped (only valid for format jsonp; since 2.8)"
273 description: "returns logo URLs to scaled images"
295 /suggestions/{number}.{format}:
299 summary: "Retrieve Suggested Podcasts"
303 description: "maximum number of podcasts to return"
309 description: "Format of the response"
312 $ref: "#/components/schemas/Format"
315 description: "a functionname on which the response is wrapped (only valid for format jsonp; since 2.8)"
339 /api/2/devices/{username}/{deviceid}.json:
343 summary: "Update Device Data"
347 description: "Username to login"
353 description: "Device Id"
356 $ref: "#/components/schemas/DeviceId"
364 $ref: '#/components/schemas/DeviceUpdateData'
368 /api/2/devices/{username}.json:
372 summary: "List Devices"
376 description: "Username to login"
389 /api/2/updates/{username}/{deviceid}.json:
393 summary: "Get Device Updates"
397 description: "Username to login"
403 description: "Device Id"
406 $ref: "#/components/schemas/DeviceId"
409 description: "`timestamp` when updates have last been retrieved"
413 - name: "include_actions"
415 description: "Default: false, since 2.10"
417 $ref: "#/components/schemas/DeviceId"
427 /api/2/sync-devices/{username}.json:
430 - "Device Synchronization"
431 summary: "Get Sync Status"
435 description: "Username to login"
450 - "Device Synchronization"
451 summary: "Start / Stop Sync"
455 description: "Username to login"
466 $ref: '#/components/schemas/DeviceSynchronizationRequest'
474 /api/2/favorites/{username}.json:
478 summary: "Get Favorite Episodes"
482 description: "username for which the favorites should be returned"
495 /subscriptions/{username}/{deviceid}.{format}:
499 summary: "Update Device Data"
503 description: "username for which subscriptions should be returned"
509 description: "Device Id"
512 $ref: "#/components/schemas/DeviceId"
515 description: "Format of the response"
518 $ref: "#/components/schemas/Format"
521 description: "a function name on which the response is wrapped (only valid for format jsonp; since 2.8)"
534 description: "Invalid user"
536 description: "Invalid device ID"
538 description: "Invalid format"
542 summary: "Upload Subscriptions of Device"
546 description: "username for which subscriptions should be returned"
552 description: "Device Id"
555 $ref: "#/components/schemas/DeviceId"
558 description: "Format of the response"
561 $ref: "#/components/schemas/Format"
569 $ref: '#/components/schemas/UploadSubscriptionRequest'
574 description: "Invalid user"
576 description: "Invalid format"
577 /subscriptions/{username}.{format}:
581 summary: "Get All Subscriptions"
585 description: "username for which subscriptions should be returned"
591 description: "Format of the response"
594 $ref: "#/components/schemas/Format"
597 description: "a function name on which the response is wrapped (only valid for format jsonp; since 2.8)"
610 description: "Invalid user"
612 description: "Invalid format"
613 /api/2/subscriptions/{username}/{deviceid}.json:
617 summary: "Upload Subscription Changes"
621 description: "username for which subscriptions should be returned"
627 description: "Device Id"
630 $ref: "#/components/schemas/DeviceId"
638 $ref: '#/components/schemas/UploadSubscriptionChangesRequest'
647 description: "Invalid format"
651 summary: "Get Subscription Changes"
655 description: "username for which subscriptions should be returned"
661 description: "Device Id"
664 $ref: "#/components/schemas/DeviceId"
667 description: "the `timestamp` value of the last response"
680 /api/2/episodes/{username}.json:
684 summary: "Upload Episode Actions"
688 description: "username for which the actions will be set"
699 $ref: '#/components/schemas/SetEpisodeActionsRequest'
710 summary: "Get Episode Actions"
714 description: "username for which the actions will be retrieved"
720 description: "The URL of a Podcast feed; if set, only actions for episodes of the given podcast are returned"
726 description: "A Device ID; if set, only actions for the given device are returned"
731 description: "Only episode actions since the given timestamp are returned"
736 description: "If true, only the latest actions is returned for each episode (added in 2.1)"
748 /api/2/settings/{username}/{scope}.json:
752 summary: "Save Settings"
756 description: "username for which the settings will be saved"
764 $ref: "#/components/schemas/SettingsScope"
767 description: "Feed URL of a podcast (required for scope podcast and episode)"
772 description: "(required for scope device)"
774 $ref: "#/components/schemas/DeviceId"
777 description: "media URL of the episode (required for scope episode)"
787 $ref: '#/components/schemas/SaveSettingsRequest'
798 summary: "Save Settings"
802 description: "username for which the settings will be saved"
810 $ref: "#/components/schemas/SettingsScope"
813 description: "Feed URL of a podcast (required for scope podcast and episode)"
818 description: "(required for scope device)"
820 $ref: "#/components/schemas/DeviceId"
823 description: "media URL of the episode (required for scope episode)"
832 description: "if the the user already has a podcast list with the (generated) name"
833 /api/2/lists/{username}/create.{format}:
837 summary: "Create Podcast List"
841 description: "username for which a new podcast list should be created"
849 $ref: "#/components/schemas/Format"
872 /api/2/lists/{username}.json:
876 summary: "Get User’s Lists"
880 description: "username for which a new podcast list should be created"
892 description: "the user was not found"
893 /api/2/lists/{username}/list/{listname}.{format}:
897 summary: "Get a Podcast List"
901 description: "username for which a new podcast list should be created"
907 description: "name of the requested podcast list"
915 $ref: "#/components/schemas/Format"
918 description: "the podcast list is returned in in the requested format"
924 description: "if the user or the list do not exist"
928 summary: "Update a Podcast List"
932 description: "username to which the list belongs"
938 description: "name of the requested podcast list"
946 $ref: "#/components/schemas/Format"
959 description: "if the podcast list has been created / updated"
961 description: "if the user or the list do not exist"
965 summary: "Delete a Podcast List"
969 description: "username to which the list belongs"
975 description: "name of the requested podcast list"
983 $ref: "#/components/schemas/Format"
988 description: "if the podcast list has been created / updated"
990 description: "if the podcast list has been deleted"
1005 description: "URL to which the gpodder.net API Endpoints should be appended"
1010 description: "Base URL of the gpodder.net feed service"
1013 description: "Time in seconds for which the values in this file can be considered valid."
1024 pattern: "^[\\w.-]+$"
1038 DeviceSynchronizationRequest:
1046 $ref: "#/components/schemas/DeviceId"
1050 $ref: "#/components/schemas/DeviceId"
1051 UploadSubscriptionRequest:
1054 $ref: "#/components/schemas/DeviceId"
1055 UploadSubscriptionChangesRequest:
1061 $ref: "#/components/schemas/DeviceId"
1065 $ref: "#/components/schemas/DeviceId"
1074 SetEpisodeActionsRequest:
1084 $ref: "#/components/schemas/DeviceId"
1086 $ref: "#/components/schemas/EpisodeActionTypes"
1102 SaveSettingsRequest: