PodcastIndex Categories API

openapi: 3.2.0
info:
  version: 1.12.1
  title: PodcastIndex.org Categories 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: Categories
  description: Categories used by the Podcast Index
paths:
  /categories/list:
    get:
      tags:
      - Categories
      summary: List
      description: 'Return all the possible categories supported by the index.


        Example: https://api.podcastindex.org/api/1.0/categories/list?pretty'
      operationId: categories/list
      security:
      - API-Key: []
        User-Agent: []
        Date: []
        Authorization: []
      parameters:
      - $ref: '#/components/parameters/pretty'
      responses:
        '200':
          $ref: '#/components/responses/categories_list'
        '400':
          $ref: '#/components/responses/400'
        '401':
          $ref: '#/components/responses/401'
components:
  schemas:
    name_category:
      description: 'The category name.

        '
      type: string
      example: Books
    count:
      description: 'Number of items returned in request

        '
      type: integer
      example: 1
    feeds_categories:
      description: 'List of categories

        '
      type:
      - array
      - 'null'
      items:
        $ref: '#/components/schemas/feed_categories'
    description_response:
      description: 'Description of the response

        '
      type: string
      example: Found matching feed
    feed_categories:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id_category'
        name:
          $ref: '#/components/schemas/name_category'
    status:
      description: 'Indicates API request status

        '
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
    id_category:
      description: 'The internal PodcastIndex.org category ID.

        '
      type: integer
      example: 2
  responses:
    '401':
      description: Not authenticated
      content:
        application/json:
          schema:
            type: string
          example: Authorization header value either not set or blank.
    categories_list:
      description: Success
      content:
        application/json:
          schema:
            type: object
            properties:
              status:
                $ref: '#/components/schemas/status'
              feeds:
                $ref: '#/components/schemas/feeds_categories'
              count:
                $ref: '#/components/schemas/count'
              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
  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
  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"
x-provenance:
  method: harvested
  publisher: PodcastIndex
  source: https://podcastindex-org.github.io/docs-api/pi_api.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)