PodcastIndex Value API
The podcast's "Value for Value" information
OpenAPI Specification
openapi: 3.0.2
info:
version: 1.12.1
title: PodcastIndex.org Add Value API
termsOfService: https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md
contact:
email: info@podcastindex.org
url: https://podcastindex.org/
license:
name: MIT
url: https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE
x-logo:
url: logo.svg
href: /
description: "Download the openapi spec in [json](pi_api.json) or [yaml](pi_api.yaml) format.\n\n# Overview\n\nThe Podcast Index (Podcast Index LLC) is a software developer focused partnership that provides tools and data to\nanyone who aspires to create new and exciting Podcast experiences without the heavy lifting of indexing,\naggregation and data management.\n\n# Example Code\n\nUsers have provided example code for working the API in the following languages:\n\n - [AWS Lambda - python](https://github.com/tbowers/python-podcastindex-org-lambda)\n - [Bash](https://github.com/suorcd/Bash-podcastindex-org-example)\n - [C#](https://github.com/ComicStrip/csharp-podcastindex-org-example)\n - [Elisp](https://github.com/sabexx/elisp-example)\n - [Flutter/Dart](https://github.com/crediblecreative/flutter-dart-podcastindex-org-example)\n - [Go](https://github.com/ComicStrip/Go-podcastindex-org-example)\n - [Go](https://github.com/kilobit/podcast-index-client)\n - [Java](https://github.com/ComicStrip/Java-podcastindex-org-example)\n - [Java](https://github.com/stucoates/PodcastIndexJavaClient)\n - [Node.js](https://github.com/ComicStrip/node.js-podcastindex-org-example)\n - [PHP](https://github.com/Podcastindex-org/example-code)\n - [Python](https://github.com/tbowers/python-podcastindex-org-example)\n - [Swift](https://github.com/ComicStrip/Swift-podcastindex-org-example)\n - ... [More](https://github.com/Podcastindex-org-Examples)\n\nDon't see your desired language, create an example repo and create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to your example code project!\n\n# Libraries\n\nUser created libraries for working with the API:\n\n - Java\n - [podcast4j](https://github.com/yusufyilmazfr/podcast4j)\n - .NET\n - [PodcastIndexSharp](https://www.nuget.org/packages/PodcastIndexSharp)\n - Node.js/npm/yarn\n - [podcast-index-api](https://www.npmjs.com/package/podcast-index-api)\n - [podcastdx-client](https://www.npmjs.com/package/podcastdx-client)\n - PHP\n - [podcastindex-php](https://github.com/LowSociety/podcastindex-php)\n - Python/pip\n - [python-podcastindex](https://pypi.org/project/python-podcastindex/)\n - R\n - [podindexr](https://github.com/rpodcast/podindexr)\n - Ruby\n - [podcast-index](https://github.com/jasonyork/podcast-index)\n - Swift\n - [PodcastIndexKit](https://github.com/SparrowTek/PodcastIndexKit)\n - Kotlin\n - [PodcastIndex-SDK](https://github.com/mr3y-the-programmer/PodcastIndex-SDK)\n - Go\n - [podcastindex](https://github.com/jjgmckenzie/podcastindex)\n - [podcastindex-go](https://github.com/koalahl/podcastindex-go)\n\nAre we missing a library? Did you create one for a different language? Create a\n[Pull Request](https://github.com/Podcastindex-org/docs-api/pulls) with a link to the new library!\n\n# Postman\n\nA collection file for use in the [Postman](https://www.postman.com/) application is available for this API.\n\n 1. Download the contents of the [Postman Docs](https://github.com/Podcastindex-org/docs-api/tree/master/Postman%20Docs) folder.\n 2. Import the `PodcastIndex.postman_collection.json` collection to Postman\n 3. Import the `PodcastIndexOrgEnvironment.postman_environment.json` to Postman\n 4. Click \"Environments\" on the left sidebar\n 5. Select the checkbox next to the PodcastIndexOrgEnvironment entry\n 6. Set `AuthKey` and `SeceretKey` values under the \"Current Value\" column using your API information\n 7. Click \"Collections\" from the sidebar\n 8. Select PodcastIndex\n 9. Select and run the endpoint to test\n\n# Contributing\n\nThe source for this API documentation is available at\n[https://github.com/Podcastindex-org/docs-api](https://github.com/Podcastindex-org/docs-api).\nSubmit an Issue or create a Pull Request.\n\n# Authentication Details\n\nSending an API request is easy. We use an Amazon-style request authorization token to secure each request.\n\n\nRegister for a free API key at https://api.podcastindex.org/\n\n\nThese headers parameters are required for each request: `User-Agent`, `X-Auth-Date`, `X-Auth-Key`, `Authorization`\n\n\nSee [Authentication](#auth) for description of parameters.\n\n# Legal\n\nLegal\n\n - [Privacy Policy](https://github.com/Podcastindex-org/legal/blob/main/PrivacyPolicy.md)\n - [Terms of Service](https://github.com/Podcastindex-org/legal/blob/main/TermsOfService.md)\n - [License](https://github.com/Podcastindex-org/docs-api/blob/master/LICENSE)\n"
servers:
- url: https://api.podcastindex.org/api/1.0
tags:
- name: Value
description: 'The podcast''s "Value for Value" information
'
paths:
/value/byfeedid:
get:
tags:
- Value
summary: By Feed ID
description: "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from the\nPodcastIndex ID.\n\n\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n\n - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\n\nNote: No API key needed for this endpoint.\n\n\nExamples:\n\n - https://api.podcastindex.org/api/1.0/value/byfeedid?id=920666&pretty\n - https://api.podcastindex.org/api/1.0/value/byfeedid?id=779873&pretty\n"
operationId: value/byfeedid
security: []
parameters:
- $ref: '#/components/parameters/id_feed_episode_pi_single'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/value_byfeedid'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/value/byfeedurl:
get:
tags:
- Value
summary: By Feed URL
description: "This call returns the information for supporting the podcast via one of the \"Value for Value\" methods from feed URL.\n\n\nAdditionally, the value block data can be accessed using static JSON files (updated every 15 minutes).\n\n - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json\n - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json\n\n\nNote: No API key needed for this endpoint.\n\n\nExamples:\n\n - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://mp3s.nashownotes.com/pc20rss.xml&pretty\n - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://lespoesiesdheloise.fr/@heloise/feed.xml&pretty\n"
operationId: value/byfeedurl
security: []
parameters:
- $ref: '#/components/parameters/url'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/value_byfeedurl'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/value/bypodcastguid:
get:
tags:
- Value
summary: By Feed GUID
description: 'This call returns the information for supporting the podcast via one of the "Value for Value" methods from podcast GUID.
Note: No API key needed for this endpoint.
Example: https://api.podcastindex.org/api/1.0/value/bypodcastguid?guid=917393e3-1b1e-5cef-ace4-edaa54e1f810&pretty
'
operationId: value/bypodcastguid
security: []
parameters:
- $ref: '#/components/parameters/guid_feed_podcast'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/value_bypodcastguid'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/value/byepisodeguid:
get:
tags:
- Value
summary: By Episode GUID
description: "This call returns the information for supporting the podcast episode via one of the \"Value for Value\" methods from\npodcast GUID and the episode GUID.\n\n\nThe `podcastguid` is the GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier\nfor the podcast. See the namespace spec for\n[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.\n\n\nThe `episodeguid` is the unique guid specified for the `<item>` in the feed but may not be globally unique.\n\n\nNote: No API key needed for this endpoint.\n\n\nExamples:\n\n - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=917393e3-1b1e-5cef-ace4-edaa54e1f810&episodeguid=PC20143&pretty\n - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=c73b1a23-1c28-5edb-94c3-10d1745d0877&episodeguid=bdea6759-a7b6-4c0d-9d1e-acca3133f4a9&pretty\n"
operationId: value/byepisodeguid
security: []
parameters:
- $ref: '#/components/parameters/podcastguid'
- $ref: '#/components/parameters/episodeguid'
- $ref: '#/components/parameters/pretty'
responses:
'200':
$ref: '#/components/responses/value_byepisodeguid'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
/value/batch/byepisodeguid:
post:
tags:
- Value
summary: Batch By Episode GUID
description: 'This call returns the information for supporting the podcast episode via one of the "Value for Value" methods from
a JSON object containing one or more podcast GUID and one or more episode GUID for the podcast.
The JSON object key shall be the `podcastguid` from the `podcast:guid` tag in the feed.
This value is a unique, global identifier for the podcast. See the namespace spec for
[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.
The value of the `podcastguid` shall be an array of `episodeguid` values.
This is the unique guid specified for the `<item>` in the feed but may not be globally unique.
Note: No API key needed for this endpoint.
'
operationId: value/batch/byepisodeguid
security: []
parameters:
- $ref: '#/components/parameters/pretty'
requestBody:
description: Get episode value data
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/value_batch_byepisodeguid'
responses:
'200':
$ref: '#/components/responses/value_batch_byepisodeguid'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
components:
schemas:
name_destination:
description: 'Name for the destination
'
type: string
example: podcaster
description_response:
description: 'Description of the response
'
type: string
example: Found matching feed
query_url:
description: 'Object containing the input query data
'
type: object
properties:
url:
$ref: '#/components/schemas/url_query'
query_guids:
description: 'Object containing the input query data
'
type: object
properties:
guids:
$ref: '#/components/schemas/guids'
query_id:
description: 'Object containing the input query data
'
type: object
properties:
id:
$ref: '#/components/schemas/id_query'
type_v4v:
description: 'Payment type
'
type: string
enum:
- lightning
- hive
- webmonetization
example: lightning
method_v4v:
description: 'Method for sending payment
'
type: string
example: keysend
destinations_v4v:
description: 'List of destinations where "Value for Value" payments should be sent.
'
type: array
items:
$ref: '#/components/schemas/destination_v4v'
query_podcastguid:
description: 'The value of the `podcastguid` argument passed to the request.
'
type: string
example: 917393e3-1b1e-5cef-ace4-edaa54e1f810
address_destination:
description: 'Address of node to receive payment
'
type: string
example: 03ae9f91a0cb8ff43840e3c322c4c61f019d8c1c3cea15a25cfc425ac605e61a4a
title_feed:
description: 'Name of the feed
'
type: string
example: Batman University
id_query_guid:
description: 'The Podcast Index Id of the podcast GUID passed as an argument to the request
'
type: integer
example: 920666
query_episodeguid:
description: 'The value of the `episodeguid` argument passed to the request.
'
type: string
example: PC20143
customKey:
description: 'The name of a custom record key to send along with the payment. May not be reported.
See the [podcast namespace spec](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#value)
and [value specification](https://github.com/Podcastindex-org/podcast-namespace/blob/main/value/value.md)
for more information.
'
type: string
nullable: true
example: '112111100'
value_byepisodeguid:
description: "Information for supporting the podcast via one of the \"Value for Value\" methods. May not be reported.\n\n\nExamples:\n - `lightning` value type: https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=169991&pretty\n - `webmonetization` value type: https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=779873&pretty\n"
type: object
nullable: true
properties:
model:
$ref: '#/components/schemas/model_v4v'
destinations:
$ref: '#/components/schemas/destinations_v4v'
title:
$ref: '#/components/schemas/title_episode'
feedTitle:
$ref: '#/components/schemas/title_feed'
customValue:
description: 'A custom value to pass along with the payment. This is considered the value that belongs to the customKey. May not be reported.
See the [podcast namespace spec](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#value)
and [value specification](https://github.com/Podcastindex-org/podcast-namespace/blob/main/value/value.md)
for more information.
'
type: string
nullable: true
example: wal_ZmqFg13NB31oek
found:
description: 'Number of value data returned.
'
type: integer
example: 4
url_query:
description: 'Value passed to request in the `url` field
'
type: string
format: URL
example: https://feeds.theincomparable.com/batmanuniversity
suggested_v4v:
description: 'Suggested amount per second of playback to send. Unit is specific to the `type`.
'
type: string
nullable: true
example: '0.00000020000'
podcastguid:
description: 'The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.
See the namespace spec for
[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.
'
type: string
example: 9b024349-ccf0-5f69-a609-6b82873eab3c
value_guid_list:
description: 'List of value blocks
'
type: array
items:
$ref: '#/components/schemas/value_byepisodeguid_batch'
value:
description: "Information for supporting the podcast via one of the \"Value for Value\" methods. May not be reported.\n\n\nExamples:\n - `lightning` value type: https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=169991&pretty\n - `webmonetization` value type: https://api.podcastindex.org/api/1.0/podcasts/byfeedid?id=779873&pretty\n"
type: object
nullable: true
properties:
model:
$ref: '#/components/schemas/model_v4v'
destinations:
$ref: '#/components/schemas/destinations_v4v'
destination_v4v:
description: 'Destination for "Value for Value" payment.
'
type: object
properties:
name:
$ref: '#/components/schemas/name_destination'
address:
$ref: '#/components/schemas/address_destination'
type:
$ref: '#/components/schemas/type_destination'
split:
$ref: '#/components/schemas/split_destination'
fee:
$ref: '#/components/schemas/fee_destination'
customKey:
$ref: '#/components/schemas/customKey'
customValue:
$ref: '#/components/schemas/customValue'
split_destination:
description: 'Share of payment the destination should receive
'
type: integer
example: 99
query_byepisodeguid:
description: 'Object containing the input query data
'
type: object
properties:
podcastguid:
$ref: '#/components/schemas/query_podcastguid'
episodeguid:
$ref: '#/components/schemas/query_episodeguid'
value_batch_byepisodeguid:
description: 'JSON data where key is the `podcastguid` and value is a list of `episodeguid` values.
'
type: object
additionalProperties:
type: array
items:
type: string
example:
917393e3-1b1e-5cef-ace4-edaa54e1f810:
- PC20141
- PC20142
- PC20143
c73b1a23-1c28-5edb-94c3-10d1745d0877:
- bdea6759-a7b6-4c0d-9d1e-acca3133f4a9
model_v4v:
description: 'Description of the method for providing "Value for Value" payments
'
type: object
properties:
type:
$ref: '#/components/schemas/type_v4v'
method:
$ref: '#/components/schemas/method_v4v'
suggested:
$ref: '#/components/schemas/suggested_v4v'
allfound:
description: 'Indicates if data was found for all `podcastguid` and `episodeguid` values.
'
type: boolean
example: true
status:
description: 'Indicates API request status
'
type: string
enum:
- 'true'
- 'false'
example: 'true'
value_byepisodeguid_batch:
description: 'Information for supporting the podcast via one of the "Value for Value" methods.
'
type: object
properties:
podcastGUID:
$ref: '#/components/schemas/podcastguid'
guid:
$ref: '#/components/schemas/guid'
title:
$ref: '#/components/schemas/title_episode'
feedTitle:
$ref: '#/components/schemas/title_feed'
model:
$ref: '#/components/schemas/model_v4v'
destinations:
$ref: '#/components/schemas/destinations_v4v'
title_episode:
description: 'Name of the episode
'
type: string
example: Gotham
guid:
description: 'The unique identifier for the episode
'
type: string
example: incomparable/batman/19
fee_destination:
description: 'Indicates if destination is included due to a fee being charged. May not be reported.
'
type: boolean
nullable: true
example: true
guids:
description: 'The `podcastguid` and `episodeguid` values passed to the request.
'
type: object
additionalProperties:
type: array
items:
type: string
example:
917393e3-1b1e-5cef-ace4-edaa54e1f810:
- PC20141
- PC20142
- PC20143
c73b1a23-1c28-5edb-94c3-10d1745d0877:
- bdea6759-a7b6-4c0d-9d1e-acca3133f4a9
query_guid_id:
description: 'Object containing the input query data
'
type: object
properties:
id:
$ref: '#/components/schemas/id_query_guid'
type_destination:
description: 'Type of destination
'
type: string
enum:
- node
example: node
id_query:
description: 'Value passed to request in the `id` field
'
type: string
example: '920666'
responses:
value_byfeedid:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
query:
$ref: '#/components/schemas/query_id'
value:
$ref: '#/components/schemas/value'
description:
$ref: '#/components/schemas/description_response'
'400':
description: Invalid request
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
description:
$ref: '#/components/schemas/description_response'
example:
status: 'false'
description: Invalid parameters
value_byfeedurl:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
query:
$ref: '#/components/schemas/query_url'
value:
$ref: '#/components/schemas/value'
description:
$ref: '#/components/schemas/description_response'
value_batch_byepisodeguid:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
query:
$ref: '#/components/schemas/query_guids'
value:
$ref: '#/components/schemas/value_guid_list'
description:
$ref: '#/components/schemas/description_response'
allFound:
$ref: '#/components/schemas/allfound'
found:
$ref: '#/components/schemas/found'
value_bypodcastguid:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
query:
$ref: '#/components/schemas/query_guid_id'
value:
$ref: '#/components/schemas/value'
description:
$ref: '#/components/schemas/description_response'
value_byepisodeguid:
description: Success
content:
application/json:
schema:
type: object
properties:
status:
$ref: '#/components/schemas/status'
query:
$ref: '#/components/schemas/query_byepisodeguid'
value:
$ref: '#/components/schemas/value_byepisodeguid'
description:
$ref: '#/components/schemas/description_response'
'401':
description: Not authenticated
content:
application/json:
schema:
type: string
example: Authorization header value either not set or blank.
parameters:
podcastguid:
name: podcastguid
in: query
description: 'The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.
See the namespace spec for
[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.
'
required: true
schema:
type: string
example: 917393e3-1b1e-5cef-ace4-edaa54e1f810
pretty:
name: pretty
in: query
description: 'If present, makes the output “pretty” to help with debugging.
Parameter shall not have a value
'
schema:
type: boolean
allowEmptyValue: true
episodeguid:
name: episodeguid
in: query
description: 'The guid specified by the `<guid>` in the episode `<item>`.
'
required: true
schema:
type: string
example: PC20143
guid_feed_podcast:
name: guid
in: query
description: 'The GUID from the `podcast:guid` tag in the feed. This value is a unique, global identifier for the podcast.
See the namespace spec for
[guid](https://github.com/Podcastindex-org/podcast-namespace/blob/main/docs/1.0.md#guid) for details.
'
required: true
schema:
type: string
example: 9b024349-ccf0-5f69-a609-6b82873eab3c
url:
name: url
in: query
description: 'Podcast feed URL
'
required: true
allowReserved: true
schema:
type: string
example: https://feeds.theincomparable.com/batmanuniversity
id_feed_episode_pi_single:
name: id
in: query
description: 'The PodcastIndex Feed ID to search for.
'
required: true
schema:
type: integer
example: 75075
securitySchemes:
User-Agent:
type: apiKey
in: header
name: User-Agent
description: 'Please identify the system/product you are using to make this request.
*Example*: `SuperPodcastPlayer/1.3`
'
API-Key:
type: apiKey
in: header
name: X-Auth-Key
description: 'Your API key string
*Example*: `UXKCGDSYGUUEVQJSYDZH`
'
Date:
type: apiKey
in: header
name: X-Auth-Date
description: 'The current UTC unix epoch time as a string. 3 minute window.
This value is an integer; round down if needed. The value shall not include a decimal point.
Value generated should match the value shown on the website https://www.epochconverter.com/.
*Example*: `1613713388`
'
Authorization:
type: apiKey
in: header
name: Authorization
description: "A SHA-1 hash of the `X-Auth-Key`, the corresponding secret and the `X-Auth-Date` value concatenated as a string.\nThe resulting hash should be encoded as a hexadecimal value, two digits per byte, using lower case letters for\nthe hex digits \"a\" through \"f\".\n\n\nThe Authorization header is computed with something like this (pseudo-code):\n\n authHeader = sha1(apiKey+apiSecret+unixTime)\n\nExample value, uses example values of `X-Auth-Key` and `X-Auth-Date` and an api secret of\n`yzJe2eE7XV-3eY576dyRZ6wXyAbndh6LUrCZ8KN|`\n\n\n*Example*: `UXKCGDSYGUUEVQJSYDZH`\n"