openapi: 3.0.3
info:
  title: Simplecast Analytics Metadata API
  description: 'The Simplecast API lets you manage and read your podcasting data on the Simplecast platform - podcasts (shows), episodes, audience analytics, and distribution channels. The API is accessed at https://api.simplecast.com and is self-describing: each response returns the actions available to the authenticated user. Authentication uses a bearer token obtained from the Private Apps page in the Simplecast dashboard (authorization: Bearer {token}). List endpoints support limit and offset query parameters for pagination. The API is predominantly read-only (HTTP GET); a small number of write operations exist, such as uploading episode audio. Simplecast is owned by SiriusXM Media. Endpoint paths in this document are derived from Simplecast''s official public Postman collection and API documentation; request and response schemas are lightly modeled where the docs do not publish a formal schema.'
  version: '1.0'
  contact:
    name: Simplecast
    url: https://www.simplecast.com
servers:
- url: https://api.simplecast.com
  description: Simplecast production API
security:
- bearerAuth: []
tags:
- name: Metadata
  description: Account, categories, keywords, authors, and helper resources.
paths:
  /categories:
    get:
      operationId: listCategories
      tags:
      - Metadata
      summary: List categories
      responses:
        '200':
          description: A collection of categories.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /authors/{author_id}:
    get:
      operationId: getAuthor
      tags:
      - Metadata
      summary: Retrieve an author
      parameters:
      - name: author_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested author.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /keywords/{keyword_id}:
    get:
      operationId: getKeyword
      tags:
      - Metadata
      summary: Retrieve a keyword
      parameters:
      - $ref: '#/components/parameters/KeywordId'
      responses:
        '200':
          description: The requested keyword.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /links/{link_id}:
    get:
      operationId: getLink
      tags:
      - Metadata
      summary: Retrieve a link
      parameters:
      - name: link_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The requested link.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /current_user:
    get:
      operationId: getCurrentUser
      tags:
      - Metadata
      summary: Retrieve the current user
      description: Returns information about the authenticated user.
      responses:
        '200':
          description: The current user.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /timezones:
    get:
      operationId: listTimezones
      tags:
      - Metadata
      summary: List timezones
      responses:
        '200':
          description: A collection of timezones.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Collection'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /oembed:
    get:
      operationId: getOembed
      tags:
      - Metadata
      summary: Retrieve oEmbed data
      description: Returns oEmbed data for a Simplecast resource URL.
      parameters:
      - name: url
        in: query
        required: true
        schema:
          type: string
      responses:
        '200':
          description: oEmbed response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Resource'
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  schemas:
    Collection:
      type: object
      description: A paged collection of resources. Fields are modeled; the API is self-describing.
      properties:
        collection:
          type: array
          items:
            $ref: '#/components/schemas/Resource'
        pages:
          type: object
          properties:
            total:
              type: integer
            limit:
              type: integer
            offset:
              type: integer
    Error:
      type: object
      properties:
        error:
          type: string
        message:
          type: string
    Resource:
      type: object
      description: A generic Simplecast resource. The API is self-describing; exact fields vary by type.
      properties:
        id:
          type: string
        href:
          type: string
  parameters:
    KeywordId:
      name: keyword_id
      in: path
      required: true
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid bearer token.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: 'Bearer token generated from the Private Apps page in the Simplecast dashboard. Sent as "authorization: Bearer {token}".'