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.

Was this section helpful?

What made this section unhelpful for you?

Endpoints

GET
GET
POST
POST
GET
DELETE
Was this section helpful?

What made this section unhelpful for you?

search

This section allows users to search podcasts by entering specific keywords, or other criteria.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Query Parameters

querystring Required

Specifies the search query string to find relevant podcasts.

Min length
3
per_pagenumber

Number of items to display per page.

Minimum
1
Maximum
50
Default value
20
filter_bystring

Specifies the criteria to filter the search results.

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

Response

200
Object
Ok

Response Attributes

current_pagenumber
dataarray

The data associated with the podcast.

Show child attributes

first_page_urlstring

The URL of the first page of results.

fromnumber

The starting point of the podcast.

next_page_urlstring

The URL of the next page of results.

pathstring

The path of the podcast.

per_pagenumber

The number of results per page to be displayed.

prev_page_urlstring

The URL of the previous page of results.

tonumber

The end point of the podcast.

Was this section helpful?

What made this section unhelpful for you?

GET

/api/podcasts/search?query=&per_page=&filter_by=title&page=

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

Response

{
  "current_page": 1,
  "data": [
    {
      "id": "0194ab19-cd96-7bf4-b9bf-4a19f4c12457",
      "title": "TechTalks",
      "description": "Exploring the latest in technology, gadgets, and software trends.",
      "author": "Tech World",
      "link": "https://techworld.com/",
      "image_url": "https://techworld.com/assets/images/techtalks-logo.jpg",
      "feed_url": "https://api.techworld.com/techtalks/feed",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:12.000000Z",
      "updated_at": "2025-01-05T06:26:28.000000Z",
      "episode_count": 245
    },
    {
      "id": "0194ab1a-caf4-7be0-860b-cb6e4d21c070",
      "title": "CineVibes - Movie & Streaming Podcast",
      "description": "A weekly discussion on movies, series, and streaming platforms. Watching is just the beginning!",
      "author": "CineVibes Network",
      "link": "http://www.cinevibes.com/",
      "image_url": "https://cinevibes.com/assets/images/cinevibes-podcast.jpg",
      "feed_url": "https://anchor.fm/s/abc1234/podcast/rss",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:13.000000Z",
      "updated_at": "2025-01-05T06:26:48.000000Z",
      "episode_count": 150
    },
    {
      "id": "0194ab1a-ea18-7c0f-a1e8-48cf55ce63fb",
      "title": "BusinessCast",
      "description": "Conversations about business strategies, innovation, and leadership with industry experts.",
      "author": "Business Insights",
      "link": "https://businessinsights.com/businesscast/",
      "image_url": "https://businessinsights.com/assets/images/businesscast.jpg",
      "feed_url": "https://feeds.businessinsights.com/5678.rss",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:16.000000Z",
      "updated_at": "2025-01-05T06:26:58.000000Z",
      "episode_count": 98
    }
  ],
  "first_page_url": "http://localhost:8000/api/podcasts/search?page=1",
  "from": 1,
  "next_page_url": null,
  "path": "http://localhost:8000/api/podcasts/search",
  "per_page": 20,
  "prev_page_url": null,
  "to": 3
}
Was this section helpful?

What made this section unhelpful for you?

list

This section allows users to retrieve a list of followed podcasts.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Query Parameters

per_pagenumber

Number of items to display per page.

Minimum
10
Maximum
100
Nullable:
True
Default value
20
pagenumber

Page number to display.

Minimum
1
Default value
1
order_bystring

Specify the order in which the results should be returned.

Default value
title
Enum values:
title
Order by title.
episode_count
Order by episode count.
sortstring

Sort order for the results.

Default value
asc
Enum values:
asc
Ascending order.
desc
Descending order.

Response

200
Object
Ok

Response Attributes

current_pagenumber

The response parameter denoting the current page number in pagination.

dataarray

The data returned by the API.

Show child attributes

first_page_urlstring

The URL of the first page of the podcast feed.

fromnumber

The starting point for the query results.

next_page_urlstring

The URL of the next page of the podcast feed.

pathstring

The path to access the podcast.

per_pagenumber

The number of results per page returned by the API.

prev_page_urlstring

The URL of the previous page of the podcast feed.

tonumber

The end point for the query results.

Was this section helpful?

What made this section unhelpful for you?

GET

/api/podcasts?per_page=&page=&order_by=&sort=

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

Response

{
  "current_page": 1,
  "data": [
    {
      "id": "0194ab0f-7d13-72ad-a23b-76b9f0abda5b",
      "title": "TechTalks",
      "description": "Exploring the latest in technology, gadgets, and software trends.",
      "author": "Tech World",
      "link": "https://techworld.com/",
      "image_url": "https://techworld.com/assets/images/techtalks-logo.jpg",
      "feed_url": "https://api.techworld.com/techtalks/feed",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:12.000000Z",
      "updated_at": "2025-01-05T06:26:28.000000Z",
      "episode_count": 245
    },
    {
      "id": "0194ab0f-99af-70dc-abdd-95077c75ea4f",
      "title": "CineVibes - Movie & Streaming Podcast",
      "description": "A weekly discussion on movies, series, and streaming platforms. Watching is just the beginning!",
      "author": "CineVibes Network",
      "link": "http://www.cinevibes.com/",
      "image_url": "https://cinevibes.com/assets/images/cinevibes-podcast.jpg",
      "feed_url": "https://anchor.fm/s/abc1234/podcast/rss",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:13.000000Z",
      "updated_at": "2025-01-05T06:26:48.000000Z",
      "episode_count": 150
    },
    {
      "id": "0194ab0f-beff-7545-ba71-1caf523acbc9",
      "title": "BusinessCast",
      "description": "Conversations about business strategies, innovation, and leadership with industry experts.",
      "author": "Business Insights",
      "link": "https://businessinsights.com/businesscast/",
      "image_url": "https://businessinsights.com/assets/images/businesscast.jpg",
      "feed_url": "https://feeds.businessinsights.com/5678.rss",
      "is_visible": true,
      "created_at": "2025-01-05T06:26:16.000000Z",
      "updated_at": "2025-01-05T06:26:58.000000Z",
      "episode_count": 98
    }
  ],
  "first_page_url": "http://localhost:8000/api/podcasts?page=1",
  "from": 1,
  "next_page_url": null,
  "path": "http://localhost:8000/api/podcasts",
  "per_page": 20,
  "prev_page_url": null,
  "to": 13
}
Was this section helpful?

What made this section unhelpful for you?

create one

This section allows users to create podcasts by providing the podcast feed url. The podcast episodes will be processed in background.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Body Parameters

feed_urlstring (uri)Required

The body parameter specifying the URL of the podcast feed to create and follow.

Response

201
Object
Created

Response Attributes

idstring

The response parameter representing the unique identifier of the podcast.

titlestring

The response parameter containing the title or name of the podcast.

descriptionstring

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

authorstring

The response parameter containing information about the author of the podcast.

linkstring

The response parameter containing the URL link associated with the podcast.

image_urlstring

The response parameter containing the URL of the image associated with the podcast.

feed_urlstring

The body parameter specifying the URL of the podcast feed to create and follow.

is_visibleboolean

The response parameter indicating whether the podcast is visible or hidden.

created_atstring

The response parameter indicating the date and time the podcast was created.

updated_atstring

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

episode_countnumber

The response parameter indicating the total number of episodes available for the podcast.

422
Object
Invalid URL.

Response Attributes

messagestring

The response parameter that provides a message related to the operation status or outcome.

errorsobject

The response parameter that contains any errors encountered during the operation.

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

POST

/api/podcasts

Select
1 2 3 4 5 6 curl --location 'http://aonsoku-podcast.test/api/podcasts' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \ --data '{ "feed_url": "http://podcasturl.com/feed.xml" }'

Response

{
  "id": "0194ab0d-962f-7df9-acb1-7bd23b0b3ddb",
  "title": "TechTalks",
  "description": "Exploring the latest in technology, gadgets, and software trends.",
  "author": "Tech World",
  "link": "https://techworld.com/",
  "image_url": "https://techworld.com/assets/images/techtalks-logo.jpg",
  "feed_url": "https://api.techworld.com/techtalks/feed",
  "is_visible": false,
  "created_at": "2025-01-05T06:26:12.000000Z",
  "updated_at": "2025-01-05T06:26:28.000000Z",
  "episode_count": null
}
Was this section helpful?

What made this section unhelpful for you?

create many

This section allows users to create podcasts by providing the podcast feed url. The podcast episodes will be processed in background.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Body Parameters

feed_urlsarray

array with feed URLs to create multiple podcasts.

Show child attributes

Response

201
Object
Created

Response Attributes

idstring

Unique identifier for the podcast.

titlestring

Title of the podcast.

descriptionstring

Description of the podcast.

authorstring

Name of the author of the podcast.

linkstring

URL link for the podcast.

image_urlstring

URL for the podcast's image.

feed_urlstring

URL for the podcast feed.

is_visibleboolean

Flag indicating if the podcast is visible.

created_atstring

Date and time when the podcast was created.

updated_atstring

Date and time when the podcast was last updated.

episode_countnumber

Total number of episodes for the podcast.

422
Object
Invalid URL.

Response Attributes

messagestring

A message related to the operation status or outcome.

errorsobject

Any errors encountered during the operation.

Show child attributes

Was this section helpful?

What made this section unhelpful for you?

POST

/api/podcasts

Select
1 2 3 4 5 6 7 8 9 curl --location 'http://aonsoku-podcast.test/api/podcasts' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \ --data '{ "feed_urls": [ "http://podcasturl.com/feed.xml", "http://another-podcasturl.com/feed.xml" ] }'

Response

[
  {
    "id": "0194ab0d-05e5-7229-b6fa-d4e113eff2ed",
    "title": "TechTalks",
    "description": "Exploring the latest in technology, gadgets, and software trends.",
    "author": "Tech World",
    "link": "https://techworld.com/",
    "image_url": "https://techworld.com/assets/images/techtalks-logo.jpg",
    "feed_url": "https://api.techworld.com/techtalks/feed",
    "is_visible": true,
    "created_at": "2025-01-05T06:26:12.000000Z",
    "updated_at": "2025-01-05T06:26:28.000000Z",
    "episode_count": 245
  },
  {
    "id": "0194ab0d-1ce5-7e24-a552-854cc2946536",
    "title": "CineVibes - Movie & Streaming Podcast",
    "description": "A weekly discussion on movies, series, and streaming platforms. Watching is just the beginning!",
    "author": "CineVibes Network",
    "link": "http://www.cinevibes.com/",
    "image_url": "https://cinevibes.com/assets/images/cinevibes-podcast.jpg",
    "feed_url": "https://anchor.fm/s/abc1234/podcast/rss",
    "is_visible": true,
    "created_at": "2025-01-05T06:26:13.000000Z",
    "updated_at": "2025-01-05T06:26:48.000000Z",
    "episode_count": 150
  },
  {
    "id": "0194ab0d-3bc5-7dac-8635-598775ff04fa",
    "title": "BusinessCast",
    "description": "Conversations about business strategies, innovation, and leadership with industry experts.",
    "author": "Business Insights",
    "link": "https://businessinsights.com/businesscast/",
    "image_url": "https://businessinsights.com/assets/images/businesscast.jpg",
    "feed_url": "https://feeds.businessinsights.com/5678.rss",
    "is_visible": true,
    "created_at": "2025-01-05T06:26:16.000000Z",
    "updated_at": "2025-01-05T06:26:58.000000Z",
    "episode_count": 98
  }
]
Was this section helpful?

What made this section unhelpful for you?

show

This section allows users to retrieve information about individual followed podcasts. Users can access details such as episode lists, descriptions, and metadata for each podcast.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Query Parameters

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.
pagenumber

Page number to display.

Minimum
1
Min length
1
Default value
1

Path Parameters

idstring Required

Unique identifier for the podcast.

Response

200
Object
Ok

Response Attributes

podcastobject

The unique identifier for the podcast.

Show child attributes

episodesobject

The episodes associated with the podcast.

Show child attributes

404
Object
Not Found

Response Attributes

messagestring

The message associated with the podcast.

Was this section helpful?

What made this section unhelpful for you?

GET

/api/podcasts/{id}?per_page=&order_by=published_at&sort=desc&page=

Select
1 2 3 curl --location --globoff 'http://aonsoku-podcast.test/api/podcasts/{id}?order_by=published_at&sort=desc' \ --header 'APP-USERNAME: username' \ --header 'APP-SERVER-URL: http://your-server-url.com' \

Response

{
  "podcast": {
    "id": "0194ab09-e6a9-7869-878e-d1116dd2d5fa",
    "title": "TechTalks",
    "description": "Exploring the latest in technology, gadgets, and software trends.",
    "author": "Tech World",
    "link": "https://techworld.com/",
    "image_url": "https://techworld.com/assets/images/techtalks-logo.jpg",
    "feed_url": "https://api.techworld.com/techtalks/feed",
    "is_visible": true,
    "created_at": "2025-01-05T06:26:12.000000Z",
    "updated_at": "2025-01-05T06:26:28.000000Z",
    "episode_count": 2
  },
  "episodes": {
    "current_page": 1,
    "data": [
      {
        "id": "0194ab0a-137c-7382-a110-a9f3fc22afe0",
        "podcast_id": "0194ab09-e6a9-7869-878e-d1116dd2d5fa",
        "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": "0194ab0a-6421-72b8-ab82-875702888bee",
        "podcast_id": "0194ab09-e6a9-7869-878e-d1116dd2d5fa",
        "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": []
      }
    ],
    "first_page_url": "http://localhost:8000/api/podcasts/1?page=1",
    "from": 1,
    "next_page_url": "http://localhost:8000/api/podcasts/1?page=2",
    "path": "http://localhost:8000/api/podcasts/1",
    "per_page": 20,
    "prev_page_url": null,
    "to": 20
  }
}
Was this section helpful?

What made this section unhelpful for you?

unfollow

This section allows users to unfollow podcasts.

Header Parameters

APP-USERNAMEstring Required
APP-SERVER-URLstring Required

Path Parameters

idstring Required

The unique identifier of the podcast that the user wants to unfollow.

Response

204
Object
No content
404
Object
Not Found

Response Attributes

messagestring

A response message indicating the success or failure of the unfollow operation.

Was this section helpful?

What made this section unhelpful for you?

DELETE

/api/podcasts/{id}

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

Response

No content
Was this section helpful?

What made this section unhelpful for you?

Episodes

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

Endpoints

GET
GET
GET
PATCH