openapi: 3.0.3
info:
  title: Acast Publishing API
  description: >-
    The Acast Publishing API lets you programmatically query data about your
    shows and episodes, and create, update, and delete episodes straight from
    the command line or an existing CMS. It also supports placing ad markers on
    episodes for dynamic ad insertion. The API is documented openly at
    developers.acast.com but is access-gated: you authenticate with an X-API-Key
    header, and that key is issued by Acast's customer success team to accounts
    on the Ace plan or in the Acast Creator Network. API keys are scoped to a
    user and grant access only to the shows assigned to that user.


    x-endpointsModeled: The resources, HTTP methods, base host, authentication
    header, and rate limit below are confirmed from Acast's public
    documentation (developers.acast.com and the Acast Learning Center). The exact
    URL path templates and JSON schemas are MODELED as conventional REST paths
    because Acast's full reference is served behind an interactive viewer that
    requires credentials. Verify precise paths and payloads against the live
    developer portal before relying on them in production.
  version: '1.0'
  contact:
    name: Acast
    url: https://developers.acast.com/
x-endpointsModeled: true
servers:
  - url: https://api.acast.com
    description: Acast Publishing API
security:
  - apiKeyAuth: []
tags:
  - name: Shows
    description: Read podcast show metadata assigned to the API key's user.
  - name: Episodes
    description: Create, read, update, and delete episodes within a show.
  - name: Ad Markers
    description: Place or update ad markers on an episode for dynamic ad insertion.
paths:
  /shows:
    get:
      operationId: listShows
      tags:
        - Shows
      summary: List shows
      description: >-
        Lists all shows in the network that are assigned to the authenticated
        user. Path modeled; resource and method confirmed from documentation.
      responses:
        '200':
          description: A list of shows.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Show'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
  /shows/{showId}:
    parameters:
      - $ref: '#/components/parameters/ShowId'
    get:
      operationId: getShow
      tags:
        - Shows
      summary: Get a show
      description: >-
        Fetches details for a specific show, including its episode listing and
        RSS feed. Path modeled; resource and method confirmed from documentation.
      responses:
        '200':
          description: The requested show.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Show'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /shows/{showId}/episodes:
    parameters:
      - $ref: '#/components/parameters/ShowId'
    get:
      operationId: listEpisodes
      tags:
        - Episodes
      summary: List episodes for a show
      description: >-
        Returns a list of all existing episodes for a show, including each
        episode's ID. Path modeled; resource and method confirmed from
        documentation.
      responses:
        '200':
          description: A list of episodes.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimited'
    post:
      operationId: createEpisode
      tags:
        - Episodes
      summary: Create an episode
      description: >-
        Creates a new episode for a show, accepting an audio file upload (MP3
        recommended, up to 150 MB) plus episode metadata. Path modeled; resource
        and method confirmed from documentation.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/EpisodeCreate'
      responses:
        '201':
          description: The created episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '413':
          description: Audio file exceeds the 150 MB maximum.
        '429':
          $ref: '#/components/responses/RateLimited'
  /shows/{showId}/episodes/{episodeId}:
    parameters:
      - $ref: '#/components/parameters/ShowId'
      - $ref: '#/components/parameters/EpisodeId'
    get:
      operationId: getEpisode
      tags:
        - Episodes
      summary: Get an episode
      description: >-
        Fetches details for a single episode. Path modeled; resource and method
        confirmed from documentation.
      responses:
        '200':
          description: The requested episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    patch:
      operationId: updateEpisode
      tags:
        - Episodes
      summary: Update an episode
      description: >-
        Updates metadata for an existing episode. Path modeled; resource and
        method confirmed from documentation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EpisodeUpdate'
      responses:
        '200':
          description: The updated episode.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Episode'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
    delete:
      operationId: deleteEpisode
      tags:
        - Episodes
      summary: Delete an episode
      description: >-
        Deletes an episode. Path modeled; resource and method confirmed from
        documentation.
      responses:
        '204':
          description: The episode was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
  /shows/{showId}/episodes/{episodeId}/ad-markers:
    parameters:
      - $ref: '#/components/parameters/ShowId'
      - $ref: '#/components/parameters/EpisodeId'
    patch:
      operationId: updateAdMarkers
      tags:
        - Ad Markers
      summary: Place or update ad markers
      description: >-
        Sets or updates the ad markers on an episode so dynamic ad insertion
        knows where to place pre-roll, mid-roll, and post-roll ads. Disabling
        monetization per episode is not supported through the API. Path modeled;
        the ad-marker-via-PATCH operation is confirmed from documentation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdMarkers'
      responses:
        '200':
          description: The updated ad markers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdMarkers'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        User-scoped API key issued by Acast customer success to Ace plan and
        Creator Network accounts. Sent on every request in the X-API-Key header.
  parameters:
    ShowId:
      name: showId
      in: path
      required: true
      description: The unique identifier of the show.
      schema:
        type: string
    EpisodeId:
      name: episodeId
      in: path
      required: true
      description: The unique identifier of the episode.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Missing or invalid X-API-Key.
    NotFound:
      description: The requested resource does not exist or is not assigned to this user.
    RateLimited:
      description: Rate limit exceeded (60 requests/minute).
  schemas:
    Show:
      type: object
      description: A podcast show hosted on Acast.
      properties:
        id:
          type: string
        title:
          type: string
        description:
          type: string
        rssFeedUrl:
          type: string
          format: uri
        imageUrl:
          type: string
          format: uri
    Episode:
      type: object
      description: An episode belonging to a show.
      properties:
        id:
          type: string
        showId:
          type: string
        title:
          type: string
        description:
          type: string
        audioUrl:
          type: string
          format: uri
        publishDate:
          type: string
          format: date-time
        durationSeconds:
          type: integer
    EpisodeCreate:
      type: object
      description: Fields for creating a new episode, including the audio upload.
      required:
        - title
        - audio
      properties:
        title:
          type: string
        description:
          type: string
        audio:
          type: string
          format: binary
          description: Audio file, MP3 recommended at 128 kbps, up to 150 MB.
        publishDate:
          type: string
          format: date-time
    EpisodeUpdate:
      type: object
      description: Mutable episode metadata fields.
      properties:
        title:
          type: string
        description:
          type: string
        publishDate:
          type: string
          format: date-time
    AdMarkers:
      type: object
      description: Ad marker placement for dynamic ad insertion.
      properties:
        markers:
          type: array
          items:
            type: object
            properties:
              type:
                type: string
                enum:
                  - preroll
                  - midroll
                  - postroll
              offsetSeconds:
                type: integer
                description: Position of the ad break, in seconds from the start.