PodcastIndex Value API

openapi: 3.2.0
info:
  version: 1.12.1
  title: PodcastIndex.org 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 or yaml format.
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

        PodcastIndex ID.


        Additionally, the value block data can be accessed using static JSON files (updated every 15 minutes).


        - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json

        - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json


        Note: No API key needed for this endpoint.


        Examples:


        - https://api.podcastindex.org/api/1.0/value/byfeedid?id=920666&pretty

        - https://api.podcastindex.org/api/1.0/value/byfeedid?id=779873&pretty'
      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.


        Additionally, the value block data can be accessed using static JSON files (updated every 15 minutes).


        - Feeds: https://tracking.podcastindex.org/feedValueBlocks.json

        - Episodes: https://tracking.podcastindex.org/episodeValueBlocks.json


        Note: No API key needed for this endpoint.


        Examples:


        - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://mp3s.nashownotes.com/pc20rss.xml&pretty

        - https://api.podcastindex.org/api/1.0/value/byfeedurl?url=https://lespoesiesdheloise.fr/@heloise/feed.xml&pretty'
      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

        podcast GUID and the episode GUID.


        The `podcastguid` is 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 for details.


        The `episodeguid` is the unique guid specified for the `` in the feed but may not be globally unique.


        Note: No API key needed for this endpoint.


        Examples:


        - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=917393e3-1b1e-5cef-ace4-edaa54e1f810&episodeguid=PC20143&pretty

        - https://api.podcastindex.org/api/1.0/value/byepisodeguid?podcastguid=c73b1a23-1c28-5edb-94c3-10d1745d0877&episodeguid=bdea6759-a7b6-4c0d-9d1e-acca3133f4a9&pretty'
      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 for details.


        The value of the `podcastguid` shall be an array of `episodeguid` values.

        This is the unique guid specified for the `` 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:
  responses:
    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'
    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'
    '401':
      description: Not authenticated
      content:
        application/json:
          schema:
            type: string
          example: Authorization header value either not set or blank.
    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_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_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'
    '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
  schemas:
    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
    method_v4v:
      description: 'Method for sending payment

        '
      type: string
      example: keysend
    query_byepisodeguid:
      description: 'Object containing the input query data

        '
      type: object
      properties:
        podcastguid:
          $ref: '#/components/schemas/query_podcastguid'
        episodeguid:
          $ref: '#/components/schemas/query_episodeguid'
    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'
    title_episode:
      description: 'Name of the episode

        '
      type: string
      example: Gotham
    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
      - 'null'
      properties:
        model:
          $ref: '#/components/schemas/model_v4v'
        destinations:
          $ref: '#/components/schemas/destinations_v4v'
    destinations_v4v:
      description: 'List of destinations where "Value for Value" payments should be sent.

        '
      type: array
      items:
        $ref: '#/components/schemas/destination_v4v'
    value_guid_list:
      description: 'List of value blocks

        '
      type: array
      items:
        $ref: '#/components/schemas/value_byepisodeguid_batch'
    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
    name_destination:
      description: 'Name for the destination

        '
      type: string
      example: podcaster
    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
      - 'null'
      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'
    guid:
      description: 'The unique identifier for the episode

        '
      type: string
      example: incomparable/batman/19
    status:
      description: 'Indicates API request status

        '
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
    query_guids:
      description: 'Object containing the input query data

        '
      type: object
      properties:
        guids:
          $ref: '#/components/schemas/guids'
    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
    type_destination:
      description: 'Type of destination

        '
      type: string
      enum:
      - node
      example: node
    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'
    query_podcastguid:
      description: 'The value of the `podcastguid` argument passed to the request.

        '
      type: string
      example: 917393e3-1b1e-5cef-ace4-edaa54e1f810
    type_v4v:
      description: 'Payment type

        '
      type: string
      enum:
      - lightning
      - hive
      - webmonetization
      example: lightning
    found:
      description: 'Number of value data returned.

        '
      type: integer
      example: 4
    split_destination:
      description: 'Share of payment the destination should receive

        '
      type: integer
      example: 99
    url_query:
      description: 'Value passed to request in the `url` field

        '
      type: string
      format: URL
      example: https://feeds.theincomparable.com/batmanuniversity
    query_url:
      description: 'Object containing the input query data

        '
      type: object
      properties:
        url:
          $ref: '#/components/schemas/url_query'
    query_guid_id:
      description: 'Object containing the input query data

        '
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id_query_guid'
    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
    fee_destination:
      description: 'Indicates if destination is included due to a fee being charged. May not be reported.

        '
      type:
      - boolean
      - 'null'
      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'
    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
      - 'null'
      example: '112111100'
    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
      - 'null'
      example: wal_ZmqFg13NB31oek
    suggested_v4v:
      description: 'Suggested amount per second of playback to send. Unit is specific to the `type`.

        '
      type:
      - string
      - 'null'
      example: '0.00000020000'
    allfound:
      description: 'Indicates if data was found for all `podcastguid` and `episodeguid` values.

        '
      type: boolean
      example: true
    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
    id_query:
      description: 'Value passed to request in the `id` field

        '
      type: string
      example: '920666'
    description_response:
      description: 'Description of the response

        '
      type: string
      example: Found matching feed
    query_id:
      description: 'Object containing the input query data

        '
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id_query'
  parameters:
    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
    id_feed_episode_pi_single:
      name: id
      in: query
      description: 'The PodcastIndex Feed ID to search for.

        '
      required: true
      schema:
        type: integer
      example: 75075
    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
    episodeguid:
      name: episodeguid
      in: query
      description: 'The guid specified by the `<guid>` in the episode `<item>`.

        '
      required: true
      schema:
        type: string
      example: PC20143
    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
    url:
      name: url
      in: query
      description: 'Podcast feed URL

        '
      required: true
      allowReserved: true
      schema:
        type: string
      example: https://feeds.theincomparable.com/batmanuniversity
  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"