# Listener Developers

> Build on Listener: the REST API, OAuth, webhooks and MCP server behind Listener and Listener Networks podcast analytics. Base URL https://api.listener.com. Every /v1 request sends Authorization: Bearer lsk_… (API key) or lat_… (OAuth token). Errors are typed ({error:{type,code,message,param,doc_url,request_id}}); lists use {object:"list",data,has_more,next_cursor}. Writes accept dry_run and Idempotency-Key; deletes and metered writes need confirm=true.

## Get started

- [Accounts & workspaces](https://developers.listener.com/md/docs/accounts.md): How Listener creators, networks, subnetworks and team members map onto the API.
- [Authentication](https://developers.listener.com/md/docs/authentication.md): API keys, how to send them, scopes and presets, rotation, and keeping keys out of browsers.
- [Introduction](https://developers.listener.com/md/docs/introduction.md): What the Listener API is, who it is for, and how its pieces fit together.
- [OAuth 2.0](https://developers.listener.com/md/docs/oauth.md): Let Listener users connect your app with “Sign in with Listener”, using the authorization code flow with PKCE.
- [Partner integrations](https://developers.listener.com/md/docs/partners.md): Connect your platform to Listener end to end, for example a podcast host. OAuth sign-in, show identity, social accounts, automatic clusters, webhooks, metrics, co-branded pages and ad-server delivery.
- [Quickstart](https://developers.listener.com/md/docs/quickstart.md): Create a key, make your first request and read your reach, in about two minutes.
- [Scopes](https://developers.listener.com/md/docs/scopes.md): Every scope an API key or OAuth grant can carry, and what each one unlocks.

## Core concepts

- [Data sources, freshness & retention](https://developers.listener.com/md/docs/data-sources.md): Where every number comes from, how often it refreshes, what is stored per post, how long data is kept, and what is not built yet.
- [Errors](https://developers.listener.com/md/docs/errors.md): The error object, every error type and code, and how to handle each.
- [Data freshness](https://developers.listener.com/md/docs/freshness.md): How current each platform’s numbers are, how to detect stale data, and how to refresh it.
- [Idempotency](https://developers.listener.com/md/docs/idempotency.md): Retry writes safely with the Idempotency-Key header.
- [Metrics glossary](https://developers.listener.com/md/docs/metrics.md): Reach categories, unique-account mode, EMV, CPM and the other numbers the API returns.
- [Pagination](https://developers.listener.com/md/docs/pagination.md): Cursor-based lists with limit, cursor, has_more and next_cursor.
- [Rate limits](https://developers.listener.com/md/docs/rate-limits.md): Per-credential request budgets, the headers that report them, and how to back off.
- [Requests & responses](https://developers.listener.com/md/docs/requests.md): Hosts, formats, ids, timestamps, headers, caching and CORS. The conventions every endpoint shares.
- [Testing with dry_run](https://developers.listener.com/md/docs/testing.md): There is no sandbox. Here is how to build and test safely against real workspaces.
- [Time windows](https://developers.listener.com/md/docs/time-windows.md): How analytics windows resolve, how growth is compared, and what coverage tells you.
- [Versioning](https://developers.listener.com/md/docs/versioning.md): Dated API versions, the Listener-Version header, and what counts as a breaking change.

## Webhooks & events

- [Events API](https://developers.listener.com/md/docs/events.md): List and fetch the events behind webhooks, for polling, backfills and reconciliation.
- [Best practices](https://developers.listener.com/md/docs/webhooks/best-practices.md): Build webhook handlers that are fast, safe and correct under retries.
- [Set up an endpoint](https://developers.listener.com/md/docs/webhooks/endpoints.md): Register a webhook URL, choose its events, store the secret and send a test.
- [Event types](https://developers.listener.com/md/docs/webhooks/event-types.md): Every event Listener sends, where it comes from, and an example payload for each.
- [Webhooks](https://developers.listener.com/md/docs/webhooks.md): Get a signed HTTPS request the moment something changes in a workspace.
- [Retries & auto-disable](https://developers.listener.com/md/docs/webhooks/retries.md): What Listener does when your endpoint is slow, down or failing, and how to recover.
- [Verify signatures](https://developers.listener.com/md/docs/webhooks/signatures.md): Check the Listener-Signature header so you only act on requests that really came from Listener.

## MCP & SDKs

- [Connect an AI assistant](https://developers.listener.com/md/docs/mcp.md): Give Claude, ChatGPT or Cursor access to a Listener workspace through the MCP server.
- [SDKs](https://developers.listener.com/md/docs/sdks.md): Official TypeScript and Python clients with typed methods, auto-pagination, retries, idempotency, webhook verification and OAuth helpers.

## Resources

- [Changelog](https://developers.listener.com/md/changelog.md): Every change to the Listener API, newest first. Breaking changes always ship as a new dated version.
- [Support](https://developers.listener.com/md/support.md): How to get help with the Listener API, report a problem or disclose a security issue.

## API reference

- [API reference](https://developers.listener.com/md/api.md): Every endpoint, grouped by resource.
- [Meta API](https://developers.listener.com/md/api/meta.md): API root, the OpenAPI document and the calling credential's workspace.
- [Workspace & shows API](https://developers.listener.com/md/api/workspace-and-shows.md): The workspace (network, subnetwork or solo show), its shows, plan, team, integrations and public profiles.
- [Episodes API](https://developers.listener.com/md/api/episodes.md): Episodes per show, search, transcripts, tags, goals and Substack download figures.
- [Analytics API](https://developers.listener.com/md/api/analytics.md): Account-level reach, timelines, rankings, platform stats and recent content. These endpoints cost 2 rate-limit tokens.
- [Clusters API](https://developers.listener.com/md/api/clusters.md): Episode clusters (an episode plus its clips and posts), cluster reports and timelines, and the AI cluster builder.
- [Campaigns API](https://developers.listener.com/md/api/campaigns.md): Sponsorship campaigns, slots, cluster links, brand profiles and air checks.
- [Reports API](https://developers.listener.com/md/api/reports.md): Shared reports, report templates and report automations.
- [Sponsors API](https://developers.listener.com/md/api/sponsors.md): Sponsor matching, network bundle opportunities and sponsorship packages.
- [Library & research API](https://developers.listener.com/md/api/library-and-research.md): Workspace library files, web research, podcast search and insertion-order parsing.
- [Refresh API](https://developers.listener.com/md/api/refresh.md): Metered actions: platform refreshes and Spotify / Apple data requests.
- [Partner integrations API](https://developers.listener.com/md/api/partner-integrations.md): For hosting and ad-tech partners: discover and connect a show's accounts, set its podcast identity, look up episodes by your own ids, control auto-build, and record ad-server delivery on campaigns.
- [Webhooks & events API](https://developers.listener.com/md/api/webhooks-and-events.md): Webhook endpoints, deliveries and the Events API.

## Optional

- [OpenAPI document](https://api.listener.com/v1/openapi.json): the full machine-readable spec
- [Full documentation in one file](https://developers.listener.com/llms-full.txt)
- [MCP server](https://mcp.listener.com/mcp): connect an AI assistant directly