PodcastIndex Categories API

openapi: 3.0.2
info:
  version: 1.12.1
  title: PodcastIndex.org Add 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](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: 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:
    feed_categories:
      type: object
      properties:
        id:
          $ref: '#/components/schemas/id_category'
        name:
          $ref: '#/components/schemas/name_category'
    description_response:
      description: 'Description of the response

        '
      type: string
      example: Found matching feed
    name_category:
      description: 'The category name.

        '
      type: string
      example: Books
    feeds_categories:
      description: 'List of categories

        '
      type: array
      nullable: true
      items:
        $ref: '#/components/schemas/feed_categories'
    status:
      description: 'Indicates API request status

        '
      type: string
      enum:
      - 'true'
      - 'false'
      example: 'true'
    count:
      description: 'Number of items returned in request

        '
      type: integer
      example: 1
    id_category:
      description: 'The internal PodcastIndex.org category ID.

        '
      type: integer
      example: 2
  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
  responses:
    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
    '401':
      description: Not authenticated
      content:
        application/json:
          schema:
            type: string
          example: Authorization header value either not set or blank.
  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"