Workspace & shows

The workspace (network, subnetwork or solo show), its shows, plan, team, integrations and public profiles.

GETList shows
GETRetrieve a show
PATCHUpdate a show's public profile
GETRetrieve the plan
GETRetrieve the team
GETList subnetworks
GETBuild public and app URLs
PATCHUpdate the network's public profile
PUTSet the network's default EMV rates
GETList platform integrations
GETRetrieve data freshness and refresh status

List shows

GET/v1/shows

shows:read

The workspace's shows with profile, plan, connected platforms and public URLs.

category matches any of a show's categories (case-insensitive); search matches name, handle and description. Hidden shows (every category hidden on the profile) are left out unless include_hidden=true.

SDKlistener.shows.list()client.shows.list()

Query parameters

categorystringnullable
searchstringnullable
Case-insensitive text filter.
include_hiddenboolean
Default false
limitinteger1 to 100
Page size, 1–100 (default 25).
Default 25
cursorstring
Opaque cursor from the previous page's next_cursor.

Returns

200

objectstringrequired
urlstringrequired
dataarray of objectsrequired
Show child attributesHide child attributes
has_morebooleanrequired
next_cursorstringrequirednullable
Pass as cursor to get the next page; null on the last page.
metaobjectrequired
The result's non-list fields (window, coverage, freshness, totals, note …).
Show child attributesHide child attributes

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Retrieve a show

GET/v1/shows/{show_id}

shows:read

One show's full profile: hosts, categories, podcast metadata (RSS, Spotify and Apple ids), Spotify rating, sponsorship packages, past guests, collaborations, per-platform connection state and freshness, and public URLs.

SDKlistener.shows.retrieve()client.shows.retrieve()

Path parameters

show_idstringrequired
A show id in this workspace (see GET /v1/shows).

Returns

200

idstringrequired
namestringrequired
planstringrequired
podcast_metadataobjectrequired
Show child attributesHide child attributes
app_urlstringrequired
computed_atstringrequired
cache_age_secondsnumberrequired
objectstringrequired
handlestring
Default ""
imagestringnullable
descriptionstring
Default ""
authorstring
Default ""
websitestringnullable
categoriesarray of strings
hidden_categoriesarray of strings
main_platformstringnullable
agency_managedboolean
Default false
created_bystringnullable
created_atstringnullable
updated_atstringnullable
hostsarray of objects
Show child attributesHide child attributes
show_host_sectionboolean
Default false
talentarray of objects
Show child attributesHide child attributes
spotify_ratingobjectnullable
Show child attributesHide child attributes
platformsarray of objects
Show child attributesHide child attributes
connected_platformsarray of strings
freshnessmap of object
Show child attributesHide child attributes
stale_platformsarray of strings
sponsorship_packagesarray of objects
collaborationsarray of objects
Show child attributesHide child attributes
past_guestsarray of objects
Show child attributesHide child attributes
survey_dataobjectnullable
Show child attributesHide child attributes
last_cluster_updatestringnullable
last_update_statsobjectnullable
episode_countintegernullable
public_urlstringnullable

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Update a show's public profile

PATCH/v1/shows/{show_id}

shows:writeSome changes need confirmSupports dry_run

Update public-profile fields shown on https://listener.com/{handle}: name, author, logo, about, categories (up to 5), main platform, featured YouTube video (URL or 11-character id), highlighted Spotify episode (URL or 22-character id), publishing schedule, brand colours (#hex) and website. Only the fields you send change.

Changing handle needs "confirm": true: it is slugified, checked for uniqueness, and the old public URL stops resolving (nothing redirects). Custom stats, display settings, hosts, collaborations and email are never touched. The response is the exact update map.

Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.

SDKlistener.shows.update()client.shows.update()

Path parameters

show_idstringrequired
A show id in this workspace (see GET /v1/shows).

Headers

Idempotency-Keystringmax 255 chars
Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json

podcast_namestringnullable
podcast_authorstringnullable
podcast_logostringnullable
aboutstringnullable
categoriesarray of stringsnullable
Only shows whose categories contain one of these (case-insensitive substring).
main_platformstringnullable
youtube_videostringnullable
highlighted_episodestringnullable
publishing_schedulestringnullable
custom_schedulestringnullable
primary_colorstringnullable
secondary_colorstringnullable
websitestringnullable
handlestringnullable
Public URL handle (lowercase, hyphens).
dry_runboolean
true returns exactly what would be written without writing anything (the API's test mode).
Default false
confirmboolean
Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.
Default false

Returns

200

One of:

WriteResult

DryRun

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 409confirmation_required 413body_too_large 429rate_limited 500internal_error

Retrieve the plan

GET/v1/plan

shows:read

The resolved plan (explicit plan → subscription → network → free) and the premium platforms and features it unlocks. Check it before offering an integration the plan locks.

SDKlistener.plan.retrieve()client.plan.retrieve()

Returns

200

planstringrequired
plan_sourcestringrequired
One ofexplicitsubscriptionis_networkagency_manageddefault_free
is_paidbooleanrequired
premium_platformsarray of stringsrequired
Platforms the app marks isPremium (locked on the free plan).
locked_platformsarray of stringsrequired
Premium platforms this plan cannot connect.
gated_featuresmap of booleanrequired
feature → available on this plan.
writes_enabledbooleanrequired
computed_atstringrequired
cache_age_secondsnumberrequired
objectstringrequired
shows_plansmap of string
show_id → resolved plan for each managed show.
notestringnullable

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Retrieve the team

GET/v1/team

shows:read

The network team: accepted members, pending invites and talent invites per show. Emails are masked (j***@domain).

SDKlistener.team.retrieve()client.team.retrieve()

Returns

200

owner_uidstringrequired
membersarray of objectsrequired
Show child attributesHide child attributes
pending_invitesarray of objectsrequired
Show child attributesHide child attributes
team_sizeintegerrequired
Owner + accepted members.
computed_atstringrequired
cache_age_secondsnumberrequired
objectstringrequired
talent_by_showarray of objects
Show child attributesHide child attributes
notestringnullable

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

List subnetworks

GET/v1/subnetworks

shows:read

The network's subnetworks (id, name, handle, show ids, activation state, public URL). Never returns credentials. Solo workspaces get an empty list with meta.note; a subnetwork reports parent_network_uid instead.

SDKlistener.subnetworks.list()client.subnetworks.list()

Returns

200

objectstringrequired
urlstringrequired
dataarray of objectsrequired
Show child attributesHide child attributes
has_morebooleanrequired
next_cursorstringrequirednullable
Pass as cursor to get the next page; null on the last page.
metaobjectrequired
The result's non-list fields (window, coverage, freshness, totals, note …).
Show child attributesHide child attributes

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Build public and app URLs

GET/v1/urls

shows:read

Build the public share URL and in-app URL for a network, show, cluster, campaign, brand, report, chart or links page. id is the entity id (cluster id, campaign id, brand slug, report id, chart id); show_id is required for show, cluster and links pages. The entity is not checked for existence.

SDKlistener.urls.retrieve()client.urls.retrieve()

Query parameters

entitystringrequired
One ofnetworkshowclustercampaignbrandreportchartlink
idstringnullable
show_idstringnullable
A show id in this workspace (see GET /v1/shows).

Returns

200

entitystringrequired
One ofnetworkshowclustercampaignbrandreportchartlink
objectstringrequired
idstringnullable
show_idstringnullable
public_urlstringnullable
app_urlstringnullable
notestringnullable

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Update the network's public profile

PATCH/v1/network

shows:writeSome changes need confirmSupports dry_run

Update the network's public profile shown on https://network.listener.com/{handle}: name, owner, website, contact email, about, focus, categories (up to 5), founded year, layout and the AI / reach-stats toggles. Only the fields you send change.

Changing handle (^[a-z0-9-]+$) needs "confirm": true; the old public URL stops resolving. Privacy, custom domain, brand colours and sponsors are never touched. Solo workspaces have no network profile (400).

Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.

SDKlistener.network.update()client.network.update()

Headers

Idempotency-Keystringmax 255 chars
Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json

network_namestringnullable
network_ownerstringnullable
network_websitestringnullable
contact_emailstringnullable
aboutstringnullable
main_focusstringnullable
categoriesarray of stringsnullable
Only shows whose categories contain one of these (case-insensitive substring).
founded_yearstringnullable
podcast_display_layoutstringnullable
One ofgridlist
show_aibooleannullable
show_reach_statsbooleannullable
handlestringnullable
Public URL handle (lowercase, hyphens).
dry_runboolean
true returns exactly what would be written without writing anything (the API's test mode).
Default false
confirmboolean
Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.
Default false

Returns

200

One of:

WriteResult

DryRun

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 409confirmation_required 413body_too_large 429rate_limited 500internal_error

Set the network's default EMV rates

PUT/v1/network/default-emv

shows:writeSome changes need confirmSupports dry_run

Set the network-wide default EMV rates inherited by every cluster and campaign without its own override. CPMs are dollars per 1,000 impressions; like and comment rates are dollars each; every value must be a finite number ≥ 0. Needs "confirm": true because it changes EMV figures across the whole workspace.

Send "dry_run": true to get {"object": "dry_run", "would_write": …} without writing anything.

SDKlistener.network.setDefaultEmv()client.network.set_default_emv()

Headers

Idempotency-Keystringmax 255 chars
Any unique string (≤ 255 chars). Replays within 24 h return the stored response with Idempotent-Replayed: true.

Request body

application/json

long_form_cpmnumberrequired
short_form_cpmnumberrequired
like_ratenumberrequired
comment_ratenumberrequired
dry_runboolean
true returns exactly what would be written without writing anything (the API's test mode).
Default false
confirmboolean
Must be true to apply destructive or metered changes; without it the API answers 409 with a preview.
Default false

Returns

200

One of:

WriteResult

DryRun

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 409confirmation_required 413body_too_large 429rate_limited 500internal_error

List platform integrations

GET/v1/integrations

shows:read

One row per show × platform (the 18 platforms of the Integrations page): connection state (connected, pending, disconnected), last update, staleness, how it can be refreshed (server, manual_request, none), whether a refresh needs confirm, and the last stored error.

platform accepts aliases; stale_only=true keeps rows older than 36 h. For the per-show rollup with cluster freshness and pending data requests use GET /v1/integrations/status.

SDKlistener.integrations.list()client.integrations.list()

Query parameters

show_idsarray of stringsnullable
Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
platformstringnullable
A platform name (e.g. youtube, spotify, applePodcasts, instagram).
statestring
One ofallconnectedpendingdisconnected
Default "all"
stale_onlyboolean
Default false
limitinteger1 to 100
Page size, 1–100 (default 25).
Default 25
cursorstring
Opaque cursor from the previous page's next_cursor.

Returns

200

objectstringrequired
urlstringrequired
dataarray of objectsrequired
Show child attributesHide child attributes
has_morebooleanrequired
next_cursorstringrequirednullable
Pass as cursor to get the next page; null on the last page.
metaobjectrequired
The result's non-list fields (window, coverage, freshness, totals, note …).
Show child attributesHide child attributes

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error

Retrieve data freshness and refresh status

GET/v1/integrations/status

shows:read

Per show: the newest platform update, stale platforms grouped by how they can be refreshed, cluster refresh freshness (last run, failed nodes), pending Spotify / Apple data requests and the last cluster update stats. Check it before POST /v1/shows/{show_id}/platforms/{platform}/refresh, POST /v1/data-requests or a cluster refresh. include_cluster_freshness=false makes it cheaper.

SDKlistener.integrations.status()client.integrations.status()

Query parameters

show_idsarray of stringsnullable
Limit to these show ids (default: every show in the workspace). Repeat the parameter or comma-separate values.
include_cluster_freshnessboolean
Default true

Returns

200

showsarray of objectsrequired
Show child attributesHide child attributes
show_idsarray of stringsrequired
computed_atstringrequired
objectstringrequired
stale_platformsarray of strings
Platforms stale on at least one show.
freshnessmap of object
platform → oldest freshness across the scoped shows.
Show child attributesHide child attributes
pending_request_countinteger
Default 0
shows_with_stale_clustersinteger
Default 0
missing_show_idsarray of strings
cache_age_secondsnumber
Default 0
notestringnullable

Errors

400parameter_invalid 401credential_invalid 403scope_missing 404resource_not_found 429rate_limited 500internal_error