### Success Response for Get Chapters

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when retrieving episode chapters. Returns an array of chapter objects.

```json
HTTP/1.1 200 OK
{
[
{
"title": "chapter 1",
"start_time": 20,
"object": "Chapter"
},
{
"title": "chapter 2",
"start_time": 100,
"object":"Chapter"
}
],
}
```

--------------------------------

### Example User-Agent Header

Source: https://developers.podbean.com/podbean-api-docs

Include a User-Agent header in your API requests to identify your application.

```HTTP
User-Agent: MyApp/1.2.3 (Example)
```

--------------------------------

### Fetch Episodes with Pagination

Source: https://developers.podbean.com/podbean-api-docs

Use the 'offset' and 'limit' parameters to paginate through episodes. This example fetches the first 50 episodes.

```bash
curl https://api.podbean.com/v1/episodes \
-G -d 'access_token=YOUR_ACCRSS_TOKEN' -d 'offset=0' -d 'limit=50'
```

--------------------------------

### oEmbed Request Example

Source: https://developers.podbean.com/podbean-api-docs

Use this cURL command to request oEmbed data. Specify the format and the URL of the content.

```bash
curl https://api.podbean.com/v1/oembed \
-d 'format=json' \
-d 'url=https://yoursubdomain.podbean.com/e/permalink'
```

--------------------------------

### Success Response (Multiple Podcasts)

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when obtaining access tokens for multiple podcasts.

```json
HTTP/1.1 200 OK
{
  "access_token": YOUR_ACCESS_TOKEN,
  "token_type": TYPE,
  "expires_in":	SECONDS_TIL_EXPIRATION
  "token_type": "Bearer",
  "scope":"podcast_read episode_read podcast_update episode_publish private_members"
  "podcasts": [{
     "access_token": YOUR_ACCESS_TOKEN,
     "expires_in": 604800,
     "token_type": "Bearer",
     "scope": "podcast_read episode_read podcast_update episode_publish podcast_read episode_read private_members",
     "title": TITLE,
     "link": LINK,
     "podcast_id": YOUR_PODCAST_ID
   }]
}
```

--------------------------------

### Success Response (Single Podcast)

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when obtaining an access token for a single podcast.

```json
HTTP/1.1 200 OK
{
  "access_token": YOUR_ACCESS_TOKEN,
  "token_type": TYPE,
  "expires_in":	SECONDS_TIL_EXPIRATION
  "token_type": "Bearer",
  "scope":"podcast_read episode_read podcast_update episode_publish private_members"
}
```

--------------------------------

### Podbean API Success Response Example

Source: https://developers.podbean.com/podbean-api-docs

This is an example of a successful response when retrieving episode details from the Podbean API.

```json
HTTP/1.1 200 OK
{
 "episode" : {
      "id": "IWPNG2FB3F",
      "title": "Good day 8",
      "content": "Time you <b>enjoy</b> wasting, was not wasted.",
      "logo": null,
      "media_url": "https://yoursubdomain.podbean.com/mf/play/ts6tyk/2017022810121184.premium_ts6tyk.m4a",
      "player_url": "https://www.podbean.com/player-v2/?xxx=xxx",
      "permalink_url": "https://yoursubdomain.podbean.com/e/permalink",
      "publish_time": 1488276731,
      "status": "publish",
      "type": "premium",
      "season_number":1,
      "episode_number":1,
      "apple_episode_type":"full",
      "transcripts_url":"https://mcdn.podbean.com/mf/web/rtm7g2/transcript.srt",
      "content_explicit":"clean"
      "object": "Episode"
 }
}
```

--------------------------------

### Success Response for Save Chapters

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response after saving chapters. Indicates the operation was successful.

```json
HTTP/1.1 200 OK
{
     "msg":"Save chapters success."
}
```

--------------------------------

### oEmbed Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful oEmbed response, providing HTML for embedding content.

```json
{
    "version": "1.0",
    "provider_name": "Podbean",
    "provider_url": "http://podbean.org",
    "width": 500,
    "height": 100,
    "type": "rich",
    "html": "&lt;iframe src='https://www.podbean.com/player-v2/?xxx=xxx' height='100' width='100%' frameborder='0' scrolling='no' data-name='pb-iframe-player' &gt;&lt;/iframe&gt;"
}
```

--------------------------------

### Podcast Download Stats Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful JSON response containing daily download counts for a given period.

```json
{
"2023-09-10": 1,
"2023-09-11": 10,
"2023-09-12": 0,
"2023-09-13": 9,
"2023-09-14": 11,
"2023-09-15": 20,
}
```

--------------------------------

### Fetch Next Set of Episodes

Source: https://developers.podbean.com/podbean-api-docs

Continue fetching episodes by adjusting the 'offset' and 'limit' parameters. This example fetches the next 100 episodes after the initial 50.

```bash
curl https://api.podbean.com/v1/episodes \
-G -d 'access_token=YOUR_ACCRSS_TOKEN' -d 'offset=50' -d 'limit=100'
```

--------------------------------

### Get Source Statistics

Source: https://developers.podbean.com/podbean-api-docs

Use this endpoint to retrieve podcast statistics based on download sources. Specify the access token, start and end dates, and the desired period (daily or monthly).

```curl
curl https://api.podbean.com/v1/podcastStats/sources \
-G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'start=2025-09-10' -d 'end=2025-09-15' -d 'period=d'
```

--------------------------------

### Get Chapters

Source: https://developers.podbean.com/podbean-api-docs

Retrieves the chapters for a specific episode. This operation requires an access token.

```APIDOC
## GET /v1/episodes/YOUR_EPISODE_ID/chapters

### Description
Retrieves the chapters associated with a specific episode.

### Method
GET

### Endpoint
https://api.podbean.com/v1/episodes/YOUR_EPISODE_ID/chapters

### Parameters
#### Query Parameters
- **access_token** (String) - Required - The access token for authentication.

### Request Example
```bash
curl https://api.podbean.com/v1/episodes/YOUR_EPISODE_ID/chapters \
-G -d 'access_token=YOUR_ACCESS_TOKEN'
```

### Response
#### Success Response (200 OK)
- **chapters** (Object[]) - An array of Chapter Objects, each containing title, start_time, and object.

#### Response Example
```json
[
  {
    "title": "chapter 1",
    "start_time": 20,
    "object": "Chapter"
  },
  {
    "title": "chapter 2",
    "start_time": 100,
    "object": "Chapter"
  }
]
```

#### Error Response (400 Bad Request)
- **error** (String) - Indicates the type of error, e.g., "input_params_invalid".
- **error_description** (String) - Provides a description of the error, e.g., "Episode not found."
```

--------------------------------

### Success Response for Engagement Stats

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when retrieving episode engagement statistics.

```HTTP
HTTP/1.1 200 OK
{
     "average_consumption_rate":0.63,
     "average_consumption_time":19,
     "listeners":26,
     "engaged_listeners":19
}
```

--------------------------------

### User Interactions Stats Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful JSON response containing various user interaction metrics for a podcast.

```http
HTTP/1.1 200 OK
{
   "followers": 98,
   "likes": 108,
   "comments": 38,
   "total_episode_length": 1098,
}
```

--------------------------------

### Podcast Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when retrieving podcast information. It includes details like title, description, logo, and website.

```json
HTTP/1.1 200 OK
{
"podcast": {
"title": "Your Podcast title",
"desc": "Podcast desc",
"logo": "https://imglink",
"website": "https://website",
"category_name": "Technology:Podcasting",
"allow_episode_type": [
"public",
"premium"
],
"object": "Podcast"
}
}
```

--------------------------------

### Get Multiple Podcasts Access Token (Client Credentials)

Source: https://developers.podbean.com/podbean-api-docs

Use this cURL command to obtain access tokens for multiple podcasts using client ID and secret.

```bash
curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
https://api.podbean.com/v1/oauth/multiplePodcastsToken \
-X POST -d 'grant_type=client_credentials'
```

--------------------------------

### Source Stats Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example JSON response for a successful request for source statistics. It shows download counts from various podcast players and applications.

```json
{
     "Podbean App": 2547,
     "Apple Podcasts": 2048,
     "Spotify": 1965,
     "Android Player": 1487,
     "Google Chrome": 965,
     "CastBox": 386,
}
```

--------------------------------

### Episodes Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when retrieving a list of episodes. It includes episode details, pagination info, and a count.

```json
{
"episodes": [
{
"id": "IWPNG2FB3F",
"title": "Good day 8",
"content": "Time you <b>enjoy</b> wasting, was not wasted.",
"logo": "http://yoursubdomain.podbean.com/mf/web/xm46wb/2017022802474032.jpg",
"media_url": "https://yoursubdomain.podbean.com/mf/play/ts6tyk/2017022810121184.premium_ts6tyk.m4a",
"player_url": "https://www.podbean.com/player-v2/?xxx=xxx",
"permalink_url": "https://yoursubdomain.podbean.com/e/permalink",
"publish_time": 1488276731,
"status": "publish",
"type": "public",
"season_number":1,
"episode_number":1,
"apple_episode_type":"full",
"transcripts_url":"https://mcdn.podbean.com/mf/web/rtm7g2/transcript.srt",
"content_explicit":"clean"
"object": "Episode"
},
{
"id": "MMK7I2FB3D",
"title": "Good day 7",
"content": "Time you <b>enjoy</b> wasting, was not wasted.",
"logo": null,
"media_url": "https://yoursubdomain.podbean.com/mf/play/7bx8bw/2017022809580229.premium_7bx8bw.m4a",
"permalink_url": "https://yoursubdomain.podbean.com/e/permalink2",
"publish_time": 1488275882,
"status": "publish",
"type": "premium",
"season_number":1,
"episode_number":1,
"apple_episode_type":"full",
"transcripts_url":"https://mcdn.podbean.com/mf/web/rtm7g2/transcript.srt",
"content_explicit":"clean",
"object": "Episode"
}
],
"offset": 0,
"limit": 20,
"has_more": false,
"count":2
}
```

--------------------------------

### Inspect Token Invalid Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when the provided access token is invalid.

```json
HTTP/1.1 400 Bad Request
{"error":"invalid_token","error_description":""}
```

--------------------------------

### Inspect Token Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when inspecting an access token. It includes token details and validity status.

```json
HTTP/1.1 200 OK
{
  "app_id": "0ru3DTJP",
  "app_name": "podbean test app",
  "expires_in": 1484894277,
  "is_valid": true,
  "issued_at": 1484289477,
  "scopes": "podcast_read episode_read podcast_update",
  "podcast_id": "90dbib3uEd"
 }
```

--------------------------------

### Get Episode Chapters

Source: https://developers.podbean.com/podbean-api-docs

Use this endpoint to retrieve all chapters for a specific episode. Requires an access token.

```curl
curl https://api.podbean.com/v1/episodes/YOUR_EPISODE_ID/chapters \
-G -d 'access_token=YOUR_ACCESS_TOKEN'
```

--------------------------------

### File Upload Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response after authorizing a file upload. Contains a presigned URL and file key.

```json
{
    "presigned_url": "https://s3.amazonaws.com/bucket.podbean.com/tmp2/49755/abc.mp3?AWSAccessKeyId=AKIAJ47JKNDVAAHIL6SA&Expires=1488268856&Signature=4iiakzeVHgLFJ4CCu0PhQHMH2EE%3D",
    "expire_in": 600,
    "file_key" : "tmp2/49755/abc.mp3"
}
```

--------------------------------

### Platform Stats Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example JSON response for a successful request for platform statistics. It shows download counts for different operating systems and platforms.

```json
{
     "Android": 1685,
     "iOS": 1125,
     "MacOSX": 985,
     "Windows": 368,
     "Linux": 211,
     "Alexa": 36,
}
```

--------------------------------

### Get Episodes

Source: https://developers.podbean.com/podbean-api-docs

Retrieves a list of authorized podcast episodes. This endpoint allows you to fetch episodes with options for pagination.

```APIDOC
## GET /v1/episodes

### Description
Get authorized podcast episode list.

### Method
GET

### Endpoint
https://api.podbean.com/v1/episodes

### Parameters
#### Query Parameters
- **access_token** (String) - Required - The access token for authentication.
- **offset** (Int) - Optional - The (zero-based) offset of the first item in the collection to return. Default value: `0`.
- **limit** (Int) - Optional - The maximum number of entries to return. Default value: `20`. Size range: `0-100`.

#### Header Parameters
- **User-Agent** (String) - Optional - It contains the name and version number of the browser or other client application.

### Response
#### Success Response (200)
- **episodes** (Array[Object]) - Array of Episode Objects.
  - **id** (String) - The unique identifier for the episode.
  - **title** (String) - The title of the episode.
  - **content** (String) - The description or content of the episode.
  - **logo** (String) - URL of the episode's logo, can be null.
  - **media_url** (String) - The URL to stream the episode's media.
  - **player_url** (String) - The URL for the episode's player.
  - **permalink_url** (String) - A permalink URL for the episode.
  - **publish_time** (Int) - The Unix timestamp when the episode was published.
  - **status** (String) - The publishing status of the episode (e.g., "publish").
  - **type** (String) - The type of the episode (e.g., "public", "premium").
  - **season_number** (Int) - The season number for the episode.
  - **episode_number** (Int) - The episode number within its season.
  - **apple_episode_type** (String) - The episode type as recognized by Apple Podcasts.
  - **transcripts_url** (String) - URL to the episode's transcript.
  - **content_explicit** (String) - Indicates if the content is explicit (e.g., "clean").
  - **object** (String) - Indicates the object type, should be "Episode".
- **offset** (Int) - The offset used for pagination.
- **limit** (Int) - The limit used for pagination.
- **count** (Int) - The total number of episodes returned in this set.
- **has_more** (Bool) - Indicates if there are more episodes available beyond this set.

### Response Example
```json
{
  "episodes": [
    {
      "id": "IWPNG2FB3F",
      "title": "Good day 8",
      "content": "Time you <b>enjoy</b> wasting, was not wasted.",
      "logo": "http://yoursubdomain.podbean.com/mf/web/xm46wb/2017022802474032.jpg",
      "media_url": "https://yoursubdomain.podbean.com/mf/play/ts6tyk/2017022810121184.premium_ts6tyk.m4a",
      "player_url": "https://www.podbean.com/player-v2/?xxx=xxx",
      "permalink_url": "https://yoursubdomain.podbean.com/e/permalink",
      "publish_time": 1488276731,
      "status": "publish",
      "type": "public",
      "season_number":1,
      "episode_number":1,
      "apple_episode_type":"full",
      "transcripts_url":"https://mcdn.podbean.com/mf/web/rtm7g2/transcript.srt",
      "content_explicit":"clean",
      "object": "Episode"
    },
    {
      "id": "MMK7I2FB3D",
      "title": "Good day 7",
      "content": "Time you <b>enjoy</b> wasting, was not wasted.",
      "logo": null,
      "media_url": "https://yoursubdomain.podbean.com/mf/play/7bx8bw/2017022809580229.premium_7bx8bw.m4a",
      "permalink_url": "https://yoursubdomain.podbean.com/e/permalink2",
      "publish_time": 1488275882,
      "status": "publish",
      "type": "premium",
      "season_number":1,
      "episode_number":1,
      "apple_episode_type":"full",
      "transcripts_url":"https://mcdn.podbean.com/mf/web/rtm7g2/transcript.srt",
      "content_explicit":"clean",
      "object": "Episode"
    }
  ],
  "offset": 0,
  "limit": 20,
  "has_more": false,
  "count": 2
}
```

### Error Handling
- **400 Bad Request**: Returned if the provided access token is invalid.
```json
{
     "error": "invalid_token",
     "error_description": "The access token provided is invalid"
}
```
```

--------------------------------

### Upload File using cURL

Source: https://developers.podbean.com/podbean-api-docs

Example of uploading a file using cURL to a presigned URL. Ensure the Content-Type header matches your file type.

```cURL
curl -v -H "Content-Type: image/jpeg" -T /your/path/file.ext "PRESIGNED_URL"
```

--------------------------------

### Get Episodes with Pagination

Source: https://developers.podbean.com/podbean-api-docs

Retrieve episodes with support for pagination using offset and limit parameters. This allows you to fetch episodes in batches.

```APIDOC
## GET /v1/episodes

### Description
Retrieves a list of episodes with support for pagination.

### Method
GET

### Endpoint
/v1/episodes

### Parameters
#### Query Parameters
- **access_token** (string) - Required - Your API access token.
- **offset** (integer) - Required - The starting index for fetching episodes.
- **limit** (integer) - Required - The maximum number of episodes to return.

### Request Example
```bash
curl https://api.podbean.com/v1/episodes \
-G -d 'access_token=YOUR_ACCRSS_TOKEN' -d 'offset=0' -d 'limit=50'
```

### Response
#### Success Response (200)
- **has_more** (boolean) - Indicates if there are more episodes available beyond the current response.
```

--------------------------------

### Get Access Token (Client Credentials)

Source: https://developers.podbean.com/podbean-api-docs

Use this cURL command to obtain an access token for managing your own account using client ID and client secret.

```bash
curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
https://api.podbean.com/v1/oauth/token \
-X POST -d 'grant_type=client_credentials'
```

--------------------------------

### Get Episodes List

Source: https://developers.podbean.com/podbean-api-docs

Retrieve a list of authorized podcast episodes with optional pagination parameters. Use 'offset' and 'limit' to control the results.

```curl
curl https://api.podbean.com/v1/episodes \
-G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'offset=0' -d 'limit=10'
```

--------------------------------

### Podcast Download Reports Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when requesting podcast download raw data. It provides URLs for CSV files for each month.

```http
HTTP/1.1 200 OK
{
   "download_urls": {
       "2018-1": "http://example.com/example.csv",
       "2018-2": "http://example.com/example.csv",
       "2018-3": "http://example.com/example.csv",
       "2018-4": "http://example.com/example.csv",
       "2018-5": "http://example.com/example.csv",
       "2018-6": false,
       "2018-7": false,
       "2018-8": false,
       "2018-9": false,
       "2018-10": false,
       "2018-11": false,
       "2018-12": false
   }
}
```

--------------------------------

### Refresh Token Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful response when refreshing an access token. It provides a new access token and its details.

```json
HTTP/1.1 200 OK
{
  "access_token": YOUR_ACCESS_TOKEN,
  "token_type": TYPE,
  "expires_in":	SECONDS_TIL_EXPIRATION
  "token_type": "Bearer",
  "scope":"podcast_read episode_read podcast_update episode_publish",
}
```

--------------------------------

### Podcast Invalid Token Error Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when an invalid access token is provided. This indicates an authentication issue.

```json
HTTP/1.1 400 Bad Request
{
"error": "invalid_token",
"error_description": "The access token provided is invalid"
}
```

--------------------------------

### Country Stats Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful JSON response for country statistics, showing download counts per country code.

```json
{
    "US": 4026,
    "GH": 1429,
    "GB": 168,
    "IR": 145,
    "CA": 119,
    "IT": 107,
    "NL": 101,
    "IN": 94,
    "KR": 83
}
```

--------------------------------

### Get Podcast Download Reports

Source: https://developers.podbean.com/podbean-api-docs

Use this endpoint to retrieve raw data files for podcast download analytics. This feature requires a business plan or higher.

```curl
curl https://api.podbean.com/v1/analytics/podcastReports \
  -G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'podcast_id=YOUR_PODCAST_ID' -d 'year=2018'
```

--------------------------------

### User Retention Success Response

Source: https://developers.podbean.com/podbean-api-docs

Example of a successful JSON response for user retention statistics. Data is grouped by date range and includes listener counts and retention rates.

```json
{
     "Aug 04-Aug 10": [{listeners: 299, retention: 1},{listeners: 33, retention: 0.11},{listeners: 20, retention: 0.067},{listeners: 14, retention: 0.047},{listeners: 13, retention: 0.043},{listeners: 12, retention: 0.04},{listeners: 0, retention: 0}],
     "Aug 11-Aug 17": [{listeners: 424, retention: 1},{listeners: 28, retention: 0.066},{listeners: 23, retention: 0.054},{listeners: 13, retention: 0.031},{listeners: 15, retention: 0.035},{listeners: 0, retention: 0}],
     "Aug 18-Aug 24": [{listeners: 362, retention: 1},{listeners: 18, retention: 0.05},{listeners: 15, retention: 0.041},{listeners: 22, retention: 0.061},{listeners: 0, retention: 0}],
     "Aug 25-Aug 31": [{listeners: 104, retention: 1},{listeners: 15, retention: 0.144},{listeners: 16, retention: 0.154},{listeners: 1, retention: 0.01}],
     "Sep 01-Sep 07": [{listeners: 65, retention: 1},{listeners: 15, retention: 0.231},{listeners: 0, retention: 0}],
     "Sep 08-Sep 14": [{listeners: 832, retention: 1},{listeners: 5, retention: 0.06}],
     "Sep 15-Sep 21": [{listeners: 35, retention: 1}]
}
```

--------------------------------

### Podcast Download Reports Invalid Token Error Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when an invalid access token is provided for podcast download reports.

```http
HTTP/1.1 400 Bad Request
{
    "error": "invalid_token",
    "error_description": "The access token provided is invalid"
}
```

--------------------------------

### Get Multiple Podcasts Access Token By Client ID and Client Secret

Source: https://developers.podbean.com/podbean-api-docs

Obtain access tokens for multiple podcasts by making an HTTP POST request to the /v1/oauth/multiplePodcastsToken endpoint.

```APIDOC
## POST /v1/oauth/multiplePodcastsToken

### Description
Obtain an access token to manage multiple podcasts associated with your account.

### Method
POST

### Endpoint
https://api.podbean.com/v1/oauth/multiplePodcastsToken

### Headers
- **Authorization** (String) - HTTP Basic authentication using client_id as username and client_secret as password.
- **User-Agent** (String) - Identifies the client application and version.

### Parameters
- **grant_type** (String) - Required - Allowed values: `client_credentials`
- **expires_in** (Int) - Optional - Default value: `604800`. Size range: `60-604800`
- **podcast_id** (String) - Optional - The ID of the podcast. If not provided, the default podcast is used.

### Request Example
```bash
curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
https://api.podbean.com/v1/oauth/multiplePodcastsToken \
-X POST -d 'grant_type=client_credentials'
```

### Response
#### Success Response (200 OK)
- **access_token** (String) - The authorization token for the default podcast.
- **token_type** (String) - Allowed values: `Bearer`
- **expires_in** (Int) - Seconds until expiration for the default token.
- **scope** (String) - The granted scopes for the default token.
- **podcasts** (Object[]) - An array containing access tokens for all podcasts belonging to the user.
  - **access_token** (String) - Access token for a specific podcast.
  - **expires_in** (Int) - Seconds until expiration for the podcast token.
  - **token_type** (String) - Allowed values: `Bearer`.
  - **scope** (String) - The granted scopes for the podcast token.
  - **title** (String) - The title of the podcast.
  - **link** (String) - The link to the podcast.
  - **podcast_id** (String) - The ID of the podcast.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": SECONDS_TIL_EXPIRATION,
  "scope": "podcast_read episode_read podcast_update episode_publish private_members",
  "podcasts": [
     {
       "access_token": "PODCAST_ACCESS_TOKEN",
       "expires_in": 604800,
       "token_type": "Bearer",
       "scope": "podcast_read episode_read podcast_update episode_publish podcast_read episode_read private_members",
       "title": "PODCAST_TITLE",
       "link": "PODCAST_LINK",
       "podcast_id": "YOUR_PODCAST_ID"
     }
   ]
}
```

#### Error Response (400 Bad Request)
```json
{
     "error": "invalid_grant",
     "error_description": "The grant type is unauthorized for this client_id"
 }
```
```

--------------------------------

### Get Podcast Engagement Reports

Source: https://developers.podbean.com/podbean-api-docs

Use this endpoint to retrieve raw data files for podcast engagement analytics. This feature requires a business plan or higher.

```curl
curl https://api.podbean.com/v1/analytics/podcastEngagementReports \
  -G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'podcast_id=YOUR_PODCAST_ID' -d 'year=2018'
```

--------------------------------

### Get Access Token By Client ID and Client Secret

Source: https://developers.podbean.com/podbean-api-docs

Obtain an access token to manage your own account by making an HTTP POST request to the /v1/oauth/token endpoint with your client ID and client secret.

```APIDOC
## POST /v1/oauth/token

### Description
Obtain an access token to manage your own account.

### Method
POST

### Endpoint
https://api.podbean.com/v1/oauth/token

### Headers
- **Authorization** (String) - HTTP Basic authentication using client_id as username and client_secret as password.
- **User-Agent** (String) - Identifies the client application and version.

### Parameters
- **grant_type** (String) - Required - Allowed values: `client_credentials`
- **expires_in** (Int) - Optional - Default value: `604800`. Size range: `60-604800`
- **podcast_id** (String) - Optional - The ID of the podcast. If not provided, the default podcast is used.

### Request Example
```bash
curl -u YOUR_CLIENT_ID:YOUR_CLIENT_SECRET \
https://api.podbean.com/v1/oauth/token \
-X POST -d 'grant_type=client_credentials'
```

### Response
#### Success Response (200 OK)
- **access_token** (String) - The authorization token.
- **token_type** (String) - Allowed values: `Bearer`
- **expires_in** (Int) - Seconds until expiration.
- **scope** (String) - The granted scopes.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": SECONDS_TIL_EXPIRATION,
  "scope": "podcast_read episode_read podcast_update episode_publish private_members"
}
```

#### Error Response (400 Bad Request)
```json
{
     "error": "invalid_grant",
     "error_description": "The grant type is unauthorized for this client_id"
 }
```
```

--------------------------------

### Widget Initialization

Source: https://developers.podbean.com/apidoc/widget

Demonstrates how to initialize the Podbean Widget API by creating a PB class instance, which can be controlled from the parent page.

```APIDOC
## Widget Initialization

Developers can use player.js to control embeddable video and audio players, or use the Podbean Widget API. To access the JavaScript object that provides the Podbean Widget API, add the following script to your HTML page. This script exposes the PB Class to the global scope, allowing you to control the widget from the parent page. The PB constructor accepts a reference to the iframe element or its CSS selector.

### Usage Example
```javascript
var iframeElement = document.querySelector('iframe');
var widget1 = new PB(iframeElement);
var widget2 = new PB('#iframeElementID');
```
```

--------------------------------

### Get Platform Statistics

Source: https://developers.podbean.com/podbean-api-docs

Use this endpoint to retrieve podcast statistics for various platforms. Specify the access token, start and end dates, and the desired period (daily or monthly).

```curl
curl https://api.podbean.com/v1/podcastStats/platforms \
-G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'start=2025-09-10' -d 'end=2025-09-15' -d 'period=d'
```

--------------------------------

### Initialize Podbean Widget

Source: https://developers.podbean.com/apidoc/widget

Add this script to your HTML to expose the PB Class. It allows control of the widget from the parent page. The PB constructor accepts an iframe element reference or its CSS selector.

```javascript
var iframeElement = document.querySelector('iframe');
var widget1 = new PB(iframeElement);
var widget2 = new PB('#iframeElementID');
```

--------------------------------

### Get Podcast Download Stats

Source: https://developers.podbean.com/podbean-api-docs

Retrieve podcast download statistics for a specified period. Requires an access token and optionally an episode ID, start date, end date, and period (daily or monthly).

```curl
curl https://api.podbean.com/v1/podcastStats/stats \
-G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'episode_id=YOUR_EPISODE_ID' -d 'start=2023-09-10' -d 'end=2023-09-15' -d 'period=d'
```

--------------------------------

### Get Podcast

Source: https://developers.podbean.com/podbean-api-docs

Retrieves authorized podcast information. This endpoint allows you to get details about your podcast, such as its title, description, logo, and website.

```APIDOC
## GET /v1/podcast

### Description
Get authorized podcast information.

### Method
GET

### Endpoint
https://api.podbean.com/v1/podcast

### Parameters
#### Query Parameters
- **access_token** (String) - Required - The access token for authentication.

#### Header Parameters
- **User-Agent** (String) - Optional - It contains the name and version number of the browser or other client application.

### Response
#### Success Response (200)
- **podcast** (Object) - Podcast Object
  - **title** (String) - Your Podcast title
  - **desc** (String) - Podcast desc
  - **logo** (String) - URL of the podcast logo
  - **website** (String) - URL of the podcast website
  - **category_name** (String) - The category of the podcast
  - **allow_episode_type** (Array[String]) - List of allowed episode types (e.g., "public", "premium")
  - **object** (String) - Indicates the object type, should be "Podcast"

### Response Example
```json
{
  "podcast": {
    "title": "Your Podcast title",
    "desc": "Podcast desc",
    "logo": "https://imglink",
    "website": "https://website",
    "category_name": "Technology:Podcasting",
    "allow_episode_type": [
      "public",
      "premium"
    ],
    "object": "Podcast"
  }
}
```

### Error Handling
- **400 Bad Request**: Returned if the provided access token is invalid.
```json
{
  "error": "invalid_token",
  "error_description": "The access token provided is invalid"
}
```
```

--------------------------------

### File Upload Error Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when the storage limit is reached.

```json
{
    "error": "storage_limit_reach",
    "error_description": " You've uploaded too much this month. To provide a fair and sustainable uploading experience for all users, your uploads are temporarily restricted until the end of this month. Thank you for your understanding."
}
```

--------------------------------

### Widget Methods

Source: https://developers.podbean.com/apidoc/widget

Provides a list of public methods available on the widget object for controlling playback, volume, and playlist navigation.

```APIDOC
## Methods

When you get the widget object, you'll have access to the following public methods:

- **bind(eventName, listener)**: Adds a listener function for the specified eventName.
- **unbind(eventName)**: Removes all listener functions previously added for the specified eventName.
- **load(url, options)**: Reloads the iframe element with a new widget specified by the URL. All previously added event listeners will continue working. `options` is an object that allows you to define widget parameters and a callback function to be executed as soon as the new widget is ready.
- **play()**: Starts playback.
- **pause()**: Pauses playback.
- **toggle()**: Toggles the player status (play/pause).
- **seekTo(milliseconds)**: Jumps to a specific position in milliseconds.
- **setVolume(volume)**: Sets the widget volume to a value between 0 and 100.
- **next()**: Skips to the next item in the playlist.
- **prev()**: Skips to the previous item in the playlist.
- **skip(index)**: Jumps to the specified episode index (starting from 0) in the playlist.
```

--------------------------------

### Widget Parameters

Source: https://developers.podbean.com/apidoc/widget

Lists the parameters that can be configured when loading a new widget, affecting its appearance and behavior.

```APIDOC
## Parameters

These parameters can be specified when loading a new widget to customize its appearance and functionality.

- **fonts** (string): Specifies the font family for the player. Browser support applies.
- **download** (0 or 1): Determines whether to show or hide the download button.
- **share** (0 or 1): Determines whether to show or hide the share button.
- **rtl** (0 or 1): Enables right-to-left text direction (default is no).
- **skin** (integer): Specifies the player color skin, from 1 to 13.
```

--------------------------------

### Refresh Token Invalid Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when the refresh token is invalid or does not exist.

```json
HTTP/1.1 400 Bad Request
{
     "error": "invalid_grant",
     "error_description": "Authorization code doesn't exist or is invalid for the client"
 }
```

--------------------------------

### Upload File using Java and OkHttp

Source: https://developers.podbean.com/podbean-api-docs

Java method to upload a file to a presigned URL using the OkHttp library. The Content-Type header should be set appropriately.

```Java
boolean uploadFile(String presignedUrl,File file) throws IOException{
      RequestBody fileBody = RequestBody.create(null, file);

      Request request = new Request
              .Builder()
              .url(presignedUrl)
              .method("PUT",fileBody)
              .addHeader("Content-Type","audio/mpeg") // use your Content-Type 
              .build();

      Response response = client.newCall(request).execute();
      return response.code() == 200;
  }
```

--------------------------------

### Invalid Request Response

Source: https://developers.podbean.com/podbean-api-docs

Example of an error response when the grant type is unauthorized for the provided client ID.

```json
HTTP/1.1 400 Bad Request
{
     "error": "invalid_grant",
     "error_description": "The grant type is unauthorized for this client_id"
 }
```

--------------------------------

### 1. Invoking the Login Dialog

Source: https://developers.podbean.com/podbean-api-docs

This endpoint is used to initiate the OAuth 2.0 login flow, allowing third-party applications to request authorization to manage a user's podcast. It redirects the user to Podbean's login page to grant permissions.

```APIDOC
## GET https://api.podbean.com/v1/dialog/oauth

### Description
Initiates the OAuth 2.0 login flow for third-party applications to request access to user podcast data.

### Method
GET

### Endpoint
https://api.podbean.com/v1/dialog/oauth

### Parameters
#### Query Parameters
- **client_id** (String) - Required - The client identifier provided by Podbean.
- **redirect_uri** (String) - Required - The URL to redirect the user back to after authentication. Must be URL-encoded.
- **scope** (String) - Required - A space-separated list of permissions requested (e.g., `podcast_read`, `episode_publish`).
- **response_type** (String) - Optional - Determines the format of the redirect response. Allowed values: `"code"`, `"token"`.
- **state** (String) - Optional - An arbitrary unique string created by the app to guard against Cross-site Request Forgery. Size range: `0..1000`.

### Request Example
```
https://api.podbean.com/v1/dialog/oauth?redirect_uri=http%3A%2F%2FYOUR_ENCODED_REDIRECT_URL&scope=podcast_read+podcast_update+episode_publish+episode_read&response_type=code&client_id=YOUR_CLIENT_ID
```

### Response
#### Success Response (302 Found)
Redirects the user to the specified `redirect_uri` with either an authorization `code` or `access_token` in the URL parameters or fragment, depending on `response_type`.

*   **Success-Response when response_type=code**
    ```
    HTTP/1.1 302 Found
    YOUR_REDIRECT_URI?code=Mclai20remJNIal1
    ```
*   **Success-Response when response_type=token**
    ```
    HTTP/1.1 302 Found
    YOUR_REDIRECT_URI#access_token=YOUR_ACCESS_TOKEN&expires_in=604800&token_type=Bearer&scope=podcast_read+episode_read+podcast_update
    ```

#### Error Response (302 Found)
Redirects the user to the `redirect_uri` with error information.

*   **Error User Denied**
    ```
    HTTP/1.1 302 Found
    YOUR_REDIRECT_URI?error=access_denied&error_description=The+user+denied+access+to+your+application
    ```
*   **Error Params Invalid**
    ```
    HTTP/1.1 200
    {"error":"redirect_uri_mismatch","error_description":"The redirect URI provided is missing or does not match","error_uri":"http:\/\/tools.ietf.org\/html\/rfc6749#section-3.1.2"}
    ```

### Header
#### Request Headers
- **User-Agent** (String) - Required - Identifies the client application and version (e.g., `MyApp/1.2.3 (Example)`).
```

--------------------------------

### Widget Event Data Structure

Source: https://developers.podbean.com/apidoc/widget

Audio events (except PB.Widget.Events.READY) return an object containing playback progress and loading status.

```javascript
relativePosition - relative current position of the current episode, in the range of [0,1].
loadProgress     - the current value of the loading progress, in the range of [0,1].
currentPosition  - the position of the current episode (in seconds).
```

--------------------------------

### Get Episode Engagement Stats

Source: https://developers.podbean.com/podbean-api-docs

Retrieves engagement statistics for a specific podcast episode. This feature requires a paid plan or above.

```APIDOC
## GET /v1/engagementStats/stats

### Description
Retrieves engagement statistics for a specific podcast episode. This feature is available for paid plan and above.

### Method
GET

### Endpoint
https://api.podbean.com/v1/engagementStats/stats

### Parameters
#### Query Parameters
- **access_token** (String) - Required - The access token for authentication.
- **episode_id** (String) - Required - The ID of the episode for which to retrieve stats.
- **period** (String) - Optional - The time period for the stats. Accepted values are 'all_time', 'this_month', and 'last_month'. Defaults to 'all_time'.

### Request Example
```bash
curl https://api.podbean.com/v1/engagementStats/stats \
-G -d 'access_token=YOUR_ACCESS_TOKEN' -d 'episode_id=YOUR_EPISODE_ID' -d 'period=all_time'
```

### Response
#### Success Response (200)
- **Stats** (Object) - An object containing engagement statistics.
  - **average_consumption_rate** (Number) - The average consumption rate of the episode.
  - **average_consumption_time** (Number) - The average consumption time of the episode in minutes.
  - **listeners** (Number) - The total number of listeners for the episode.
  - **engaged_listeners** (Number) - The number of engaged listeners for the episode.

#### Response Example
```json
{
     "average_consumption_rate":0.63,
     "average_consumption_time":19,
     "listeners":26,
     "engaged_listeners":19
}
```

#### Error Response (400)
- **error** (String) - An error code (e.g., 'invalid_token').
- **error_description** (String) - A description of the error.
```