Place or update ad markers within an episode via PATCH so dynamic ad insertion knows where to stitch pre-roll, mid-roll, and post-roll ads. Note that disabling monetization on a per-episode basis is not currently possible through the API. Endpoint paths are modeled - see the OpenAPI x-endpointsModeled note.
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.