Github
Github

Theme switcher

Introduction

Welcome to the Aonsoku Podcast Management API documentation. This API provides a comprehensive set of endpoints for managing podcasts and their episodes, allowing you to create, retrieve, update, and delete podcast records, as well as perform searches and save episode listening progress.

Was this section helpful?

What made this section unhelpful for you?

Base URL

Sandbox:

http://aonsoku-podcast.test

Localhost:

http://localhost:8000

Language Box

Was this section helpful?

What made this section unhelpful for you?

Authentication

This section guides users on how to access and authenticate their accounts to perform various actions using the API.

The Username and Server URL values do not need to be manually created. After the first request using the credentials listed below, the API will automatically create the user for you.

Name
Header
Description
Required

Username

APP-USERNAME

Your subsonic username.

āœ…

Server URL

APP-SERVER-URL

Your subsonic server URL.

āœ…

If either of these headers is not provided, the server will respond with a 400 Bad Request status.

Was this section helpful?

What made this section unhelpful for you?

Episode updates

The API automatically searches for new episodes periodically (every 2 hours), and to minimize CPU usage, it skips episodes that have already been processed. Users can stay up-to-date with the most recent content effortless.

Was this section helpful?

What made this section unhelpful for you?

Podcasts

This section allows users to access detailed information about podcasts, including titles, descriptions, release dates, and more.

Endpoints

GET
GET
POST
POST
GET
DELETE

Episodes

This section allows users to access detailed information about podcast episodes. Users can retrieve episode titles, descriptions, release dates, and more.

Was this section helpful?

What made this section unhelpful for you?

Endpoints

GET
GET
GET
PATCH
Was this section helpful?

What made this section unhelpful for you?

search

This section allows users to search for episodes within a specific podcast by providing the podcast ID.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Query Parameters

querystring Required

Specifies the search query string to find episodes.

Minimum
3
per_pagenumber

Number of items to display per page.

Minimum
10
Maximum
100
Nullable:
True
Default value
20
order_bystring

Specify the order in which the results should be returned.

Nullable:
True
Default value
published_at
Enum values:
published_at
Order by published_at date.
title
Order by title.
duration
Order by duration value.
sortstring

Sort order for the results.

Nullable:
True
Default value
desc
Enum values:
asc
Ascending order.
desc
Descending order.
filter_bystring

Specifies the criteria to filter the search results.

Nullable:
True
Default value
both
Enum values:
title
Filter only by Title.
description
Filter only by Description.
both
Filter by Title and Description.
pagenumber

Page number to display.

Minimum
1
Default value
1

Path Parameters

idstring Required

The unique identifier of the podcast used to search for episodes.

Response

200
Object
Ok

Response Attributes

current_pagenumber

The response parameter indicating the current page of results.

dataarray

The response parameter containing the data of the episode.

Show child attributes

first_page_urlstring

The URL of the first page of results.

fromnumber

The response parameter indicating the starting point.

next_page_urlstring

The URL of the next page of results.

pathstring

The response parameter representing the path.

per_pagenumber

The query parameter specifying the number of results per page.

prev_page_urlstring

The URL of the previous page of results.

tonumber

The response parameter indicating the end point.

404
Object
Not Found

Response Attributes

messagestring

The response parameter containing a message.

Was this section helpful?

What made this section unhelpful for you?

GET

/api/episodes/podcast/{id}/search?query=&per_page=&order_by=published_at&sort=asc&filter_by=title&page=

Select
1 2 3 curl --location 'http://aonsoku-podcast.test/api/episodes/podcast/1/search?query=&order_by=published_at&sort=asc&filter_by=title' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \

Response

{
  "current_page": 1,
  "data": [
    {
      "id": "0194ab02-5c77-7f2f-b377-1ca5627655c8",
      "podcast_id": "0194ab02-9b81-7c1f-a42d-9eba2f7452ea",
      "title": "TechTalks 61 - New Year Goals and CES 2025 Highlights",
      "description": "In the LAST TECHTALKS EPISODE OF 2024, hosts @johndoe and @janedoe discuss their adventures at CES and reveal if they achieved their 2024 goals!\n\nSpecial discount with NordVPN using our link: https://nordvpn.com/techtalks\nor use the CODE: TECHTALKS\nGet 15% off your subscription at Alura using this link: https://www.alura.com/techtalks\nor use the CODE: TECHTALKS\n\nHost: John Doe. Instagram: @johndoe | Twitter/X: @johndoe\nCo-Host: Jane Doe. Instagram: @janedoe | Twitter/X: @janedoe\n\nOur Social Media:\nInstagram: @techtalkspod\nTwitter: @techtalkspod\nReddit: r/techtalkspod\n\nFan group on Telegram: https://t.me/techtalks_fans\nThis group is managed by listeners and is not officially affiliated with the podcast.\n\nLinks mentioned:\nTech Trends 2025: https://techworld.com/trends\n\n===\nProduction: Alex Smith, Maria Johnson\nEditing: Chris Doe\nCover Art: Emily Clark",
      "audio_url": "https://www.podtrac.com/pts/redirect.mp3/traffic.megaphone.fm/TECHTALKSPAASL123456.mp3?updated=1734548665",
      "image_url": "https://megaphone.imgix.net/podcasts/tech-talks-cover.jpg?ixlib=rails-4.3.1&max-w=3000&max-h=3000&fit=crop&auto=format,compress",
      "duration": 4246,
      "published_at": "2024-12-18 18:58:00",
      "created_at": "2025-01-05T04:07:37.000000Z",
      "updated_at": "2025-01-05T04:07:37.000000Z",
      "playback": []
    }
  ],
  "first_page_url": "http://localhost:8000/api/episodes/podcast/1/search?page=1",
  "from": 1,
  "next_page_url": null,
  "path": "http://localhost:8000/api/episodes/podcast/1/search",
  "per_page": 20,
  "prev_page_url": null,
  "to": 1
}
Was this section helpful?

What made this section unhelpful for you?

latest

This section allows users to access the most recent episodes from followed podcasts.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Response

200
Object
Ok

Response Attributes

idstring

The response parameter representing a unique identifier assigned to the episode.

podcast_idstring

The response parameter indicating the unique identifier of the podcast to which the episode belongs.

titlestring

The response parameter indicating the title or name of the episode.

descriptionstring

The response parameter providing a brief description or summary of the episode.

audio_urlstring

The response parameter providing the URL link to the audio file of the episode.

image_urlstring

The response parameter providing the URL link to the image associated with the episode.

durationnumber

The response parameter representing the length of the episode in terms of time duration.

published_atstring

The response parameter specifying the date and time when the episode was published.

created_atstring

The response parameter denoting the date and time when the episode was created.

updated_atstring

The response parameter indicating the date and time when the episode was last updated.

playbackarray

The response parameter specifying the playback status or information related to the episode.

Was this section helpful?

What made this section unhelpful for you?

GET

/api/episodes/latest

Select
1 2 3 curl --location 'http://aonsoku-podcast.test/api/episodes/latest' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \

Response

[
  {
    "id": "63d8716e-125b-4f3a-8d1c-2547633d51ad",
    "podcast_id": "0194aacc-382c-7aea-bdc9-38004300b134",
    "title": "TechTalks 61 - New Year Goals and CES 2025 Highlights",
    "description": "In the LAST TECHTALKS EPISODE OF 2024, hosts @johndoe and @janedoe discuss their adventures at CES and reveal if they achieved their 2024 goals!\n\nSpecial discount with NordVPN using our link: https://nordvpn.com/techtalks\nor use the CODE: TECHTALKS\nGet 15% off your subscription at Alura using this link: https://www.alura.com/techtalks\nor use the CODE: TECHTALKS\n\nHost: John Doe. Instagram: @johndoe | Twitter/X: @johndoe\nCo-Host: Jane Doe. Instagram: @janedoe | Twitter/X: @janedoe\n\nOur Social Media:\nInstagram: @techtalkspod\nTwitter: @techtalkspod\nReddit: r/techtalkspod\n\nFan group on Telegram: https://t.me/techtalks_fans\nThis group is managed by listeners and is not officially affiliated with the podcast.\n\nLinks mentioned:\nTech Trends 2025: https://techworld.com/trends\n\n===\nProduction: Alex Smith, Maria Johnson\nEditing: Chris Doe\nCover Art: Emily Clark",
    "audio_url": "https://www.podtrac.com/pts/redirect.mp3/traffic.megaphone.fm/TECHTALKSPAASL123456.mp3?updated=1734548665",
    "image_url": "https://megaphone.imgix.net/podcasts/tech-talks-cover.jpg?ixlib=rails-4.3.1&max-w=3000&max-h=3000&fit=crop&auto=format,compress",
    "duration": 4246,
    "published_at": "2024-12-18 18:58:00",
    "created_at": "2025-01-05T04:07:37.000000Z",
    "updated_at": "2025-01-05T04:07:37.000000Z",
    "playback": []
  },
  {
    "id": "d91666aa-2809-4cc5-ae7f-4ba5ae840c50",
    "podcast_id": "0194aacc-66a2-7216-8284-f9f79a544d7f",
    "title": "TechTalks 60 - AI Myths, Gadget Fails & Smart Home Disasters",
    "description": "Are smart devices really making life easier? In this episode, @johndoe and @janedoe dive into hilarious tech failures and discuss myths around AI advancements.\n\nSpecial discount with NordVPN using our link: https://nordvpn.com/techtalks\nor use the CODE: TECHTALKS\nGet 15% off your subscription at Alura using this link: https://www.alura.com/techtalks\nor use the CODE: TECHTALKS\n\nHost: John Doe. Instagram: @johndoe | Twitter/X: @johndoe\nCo-Host: Jane Doe. Instagram: @janedoe | Twitter/X: @janedoe\n\nOur Social Media:\nInstagram: @techtalkspod\nTwitter: @techtalkspod\nReddit: r/techtalkspod\n\nFan group on Telegram: https://t.me/techtalks_fans\nThis group is managed by listeners and is not officially affiliated with the podcast.\n\nLinks mentioned:\nAI Breakthroughs: https://techworld.com/ai-news\n\n===\nProduction: Alex Smith, Maria Johnson\nEditing: Chris Doe\nCover Art: Emily Clark",
    "audio_url": "https://www.podtrac.com/pts/redirect.mp3/traffic.megaphone.fm/TECHTALKSPAASL789123.mp3?updated=1733942536",
    "image_url": "https://megaphone.imgix.net/podcasts/tech-talks-ep60-cover.jpg?ixlib=rails-4.3.1&max-w=3000&max-h=3000&fit=crop&auto=format,compress",
    "duration": 3801,
    "published_at": "2024-12-11 18:37:00",
    "created_at": "2025-01-05T04:07:37.000000Z",
    "updated_at": "2025-01-05T04:07:37.000000Z",
    "playback": []
  }
]
Was this section helpful?

What made this section unhelpful for you?

show

This section allows users to access episode information.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Path Parameters

idstring Required

Unique identifier for the episode.

Response

200
Object
Ok

Response Attributes

idstring
podcast_idstring
titlestring
descriptionstring
audio_urlstring
image_urlstring
durationnumber
published_atstring
created_atstring
updated_atstring
playbackarray
404
Object

Response Attributes

messagestring
Was this section helpful?

What made this section unhelpful for you?

GET

/api/episodes/{id}

Select
1 2 3 curl --location --globoff 'http://aonsoku-podcast.test/api/episodes/{id}' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \

Response

{
  "id": "0194aaaf-b71b-7518-ae55-4a88f70c3369",
  "podcast_id": "0194aab5-6241-7752-88e3-300d174086a1",
  "title": "TechTalks 61 - New Year Goals and CES 2025 Highlights",
  "description": "In the LAST TECHTALKS EPISODE OF 2024, hosts @johndoe and @janedoe discuss their adventures at CES and reveal if they achieved their 2024 goals!\n\nSpecial discount with NordVPN using our link: https://nordvpn.com/techtalks\nor use the CODE: TECHTALKS\nGet 15% off your subscription at Alura using this link: https://www.alura.com/techtalks\nor use the CODE: TECHTALKS\n\nHost: John Doe. Instagram: @johndoe | Twitter/X: @johndoe\nCo-Host: Jane Doe. Instagram: @janedoe | Twitter/X: @janedoe\n\nOur Social Media:\nInstagram: @techtalkspod\nTwitter: @techtalkspod\nReddit: r/techtalkspod\n\nFan group on Telegram: https://t.me/techtalks_fans\nThis group is managed by listeners and is not officially affiliated with the podcast.\n\nLinks mentioned:\nTech Trends 2025: https://techworld.com/trends\n\n===\nProduction: Alex Smith, Maria Johnson\nEditing: Chris Doe\nCover Art: Emily Clark",
  "audio_url": "https://www.podtrac.com/pts/redirect.mp3/traffic.megaphone.fm/TECHTALKSPAASL123456.mp3?updated=1734548665",
  "image_url": "https://megaphone.imgix.net/podcasts/tech-talks-cover.jpg?ixlib=rails-4.3.1&max-w=3000&max-h=3000&fit=crop&auto=format,compress",
  "duration": 4246,
  "published_at": "2024-12-18 18:58:00",
  "created_at": "2025-01-05T04:07:37.000000Z",
  "updated_at": "2025-01-05T04:07:37.000000Z",
  "playback": []
}
Was this section helpful?

What made this section unhelpful for you?

progress

This section allows users to update the progress of a specific podcast episode, enabling them to track their listening progress and easily resume playback from where they left off.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Path Parameters

idstring Required

Unique identifier for the specific episode being updated.

Body Parameters

progressnumber

Value in seconds used to update the progress of the episode.

Response

200
Object
Ok

Response Attributes

progressnumber

Value in seconds used to update the progress of the episode.

completedboolean

Indicates if the progress has reached the end of the episode duration.

404
Object
Not Found

Response Attributes

messagestring

Optional message included in the response data.

422
Object
Validation exception if provided progress is not an integer.

Response Attributes

messagestring

Optional message included in the response data.

errorsobject

Contains any error messages or codes if the request encounters an issue.

Show child attributes

422
Object
Validation exception if progress not provided.

Response Attributes

messagestring

Optional message included in the response data.

errorsobject

Contains any error messages or codes if the request encounters an issue.

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

PATCH

/api/episodes/{id}/progress

Select
1 2 3 4 5 6 curl --location --request PATCH 'http://aonsoku-podcast.test/api/episodes/61/progress' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \ --data '{ "progress": 4246 }'

Response

{
  "progress": 4246,
  "completed": true
}
Was this section helpful?

What made this section unhelpful for you?