Skip to content
Listener.comDevelopers

Introduction

What the Listener API is, who it is for, and how its pieces fit together.

2 min read

The Listener API gives your code the same view of a podcast business that the Listener apps show: shows, reach across YouTube, audio and social, episodes, episode clusters, sponsorship campaigns and shared reports. It is one API for every Listener account, whether that is a single creator on listener.com or a network on Listener Networks.

The API, the MCP server, the in-app agent and the apps themselves all read through the same metric code, so a reach number you fetch here matches the number on the Analytics page for the same window.

What you can build#

Reporting pipelinesPull reach, rankings and campaign delivery into a warehouse, a spreadsheet or a client portal.Ad-ops automationCreate campaigns from insertion orders, link episode clusters to slots and track delivered CPM.Integrations for Listener usersLet any Listener workspace connect your product with “Sign in with Listener”.Event-driven workflowsReact when a campaign goes live, a cluster gains posts or a platform connection breaks.

The pieces#

SurfaceWhereUse it for
REST APIhttps://api.listener.com/v1Reading and changing workspace data from your servers and scripts.
OAuth 2.0https://api.listener.com/oauthActing on behalf of Listener users who connect your app.
Webhooks and events/v1/webhook-endpoints, /v1/eventsHearing about changes without polling everything.
MCP serverhttps://mcp.listener.com/mcpGiving Claude, ChatGPT or Cursor access to a workspace.
OpenAPI documenthttps://api.listener.com/v1/openapi.jsonGenerating clients, importing into Postman or Insomnia, feeding LLM tools.

Design principles#

  • Resource-oriented and predictable. Every payload has an object and an id, lists share one envelope, errors share one shape. See Requests & responses.
  • Honest numbers. Windowed analytics say which window they resolved, how much of it has data and how fresh each platform is. Growth is null rather than a misleading percentage when the baseline is thin. See Time windows and Data freshness.
  • Safe writes. Every write accepts dry_run, every write accepts an Idempotency-Key, and destructive or metered writes need confirm: true. See Testing with dry_run.
  • Least privilege. Keys and OAuth grants carry fine-grained scopes, and every endpoint declares the one scope it needs. See Scopes.

What the API does not do#

Some actions stay in the apps on purpose: billing and plan changes, adding or removing team members and subnetworks, connecting platform accounts (YouTube, Instagram and so on), and brand invites. You can read most of that state through the API; you change it in the app.

Using an AI assistant?:

Using an AI assistant?

Every page has a Copy page button and the whole site is available as llms.txt and llms-full.txt. If you want an assistant to work with your workspace directly, connect it to the MCP server instead.