API Reference

Read your LeetCast data programmatically. Every endpoint is scoped to a single show, authenticated by a bearer token you generate in your settings.

Generate a token Jump to endpoints

Authentication

Pass your token as a bearer credential on every request:

Authorization: Bearer lc_live_...

Tokens are scoped to a single show and a list of permissions (see Scopes). A request that asks for data outside the token's scope gets a 403. Missing tokens return 401.

Rate limits

Every token is limited to 60 requests per 60-second rolling window. Over-limit requests return 429 Too Many Requests with a Retry-After header telling you how many seconds to wait.

Scopes

Pick the minimum scopes a token needs. You can always issue a second token rather than broadening an existing one.

analytics:read

Read click, geo, device, and time-series analytics for a show.

links:read

List SmartLinks (episode, show_latest, promo) for a show.

campaigns:read

List promo campaigns and attribution data for a show.

reports:read

List sponsor reports (metadata only; no snapshot blobs).

webhooks:read

List configured webhook endpoints for a show.

webhooks:write

Create, update, delete, rotate, and test webhook endpoints.

Endpoints

GET

/api/v1/analytics

analytics:read

Aggregated analytics for a show across a date range. Returns top sources, top episodes, geo, devices, time series, and total clicks. Pass `metric=` to narrow to one.

Parameters

showIdquery · required— UUID of the show.
fromquery · required— ISO date (e.g. 2026-01-01).
toquery · required— ISO date. Must be after `from`. Max 365-day window.
metricquery · optional— One of: top_sources, top_episodes, geo, devices, time_series, total_clicks.

Example

curl -H "Authorization: Bearer lc_live_..." \
  "https://leetcast.com/api/v1/analytics?showId=SHOW&from=2026-01-01&to=2026-01-31&metric=top_sources"

GET

/api/v1/links

links:read

All SmartLinks for a show: episode links, the show-latest link, and promo drop links.

Parameters

showIdquery · required— UUID of the show.

Example

curl -H "Authorization: Bearer lc_live_..." \
  "https://leetcast.com/api/v1/links?showId=SHOW"

GET

/api/v1/campaigns

campaigns:read

Promo-swap campaigns for a show with status and guest metadata.

Parameters

showIdquery · required— UUID of the show.

Example

curl -H "Authorization: Bearer lc_live_..." \
  "https://leetcast.com/api/v1/campaigns?showId=SHOW"

GET

/api/v1/reports

reports:read

Sponsor reports for a show. Snapshot blobs are excluded — fetch the PDF via the share URL.

Parameters

showIdquery · required— UUID of the show.

Example

curl -H "Authorization: Bearer lc_live_..." \
  "https://leetcast.com/api/v1/reports?showId=SHOW"

GET

/api/v1/webhooks

webhooks:read

List webhook endpoints configured for a show.

Parameters

showIdquery · required— UUID of the show.

Example

curl -H "Authorization: Bearer lc_live_..." \
  "https://leetcast.com/api/v1/webhooks?showId=SHOW"

POST

/api/v1/webhooks

webhooks:write

Create a webhook. Response includes a `secret` used to verify incoming signatures. Store it now — it is only returned once.

Parameters

showIdbody · required— UUID of the show.
urlbody · required— HTTPS endpoint that receives signed POSTs.
eventsbody · required— Array of event types (see Webhook Events below).
descriptionbody · optional— Free-form label shown in the UI.

Example

curl -X POST -H "Authorization: Bearer lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"showId":"SHOW","url":"https://example.com/hook","events":["click.created"]}' \
  https://leetcast.com/api/v1/webhooks

POST

/api/v1/webhooks/{id}

webhooks:write

Update a webhook (toggle active, adjust events, rename).

Example

curl -X POST -H "Authorization: Bearer lc_live_..." \
  -H "Content-Type: application/json" \
  -d '{"active":false}' \
  https://leetcast.com/api/v1/webhooks/ID

DELETE

/api/v1/webhooks/{id}

webhooks:write

Delete a webhook endpoint.

Example

curl -X DELETE -H "Authorization: Bearer lc_live_..." \
  https://leetcast.com/api/v1/webhooks/ID

POST

/api/v1/webhooks/{id}/test

webhooks:write

Trigger a test delivery to verify your endpoint is reachable and signatures validate.

Example

curl -X POST -H "Authorization: Bearer lc_live_..." \
  https://leetcast.com/api/v1/webhooks/ID/test

POST

/api/v1/webhooks/{id}/rotate

webhooks:write

Rotate the signing secret. The response contains the new secret. Previous secret stops validating immediately.

Example

curl -X POST -H "Authorization: Bearer lc_live_..." \
  https://leetcast.com/api/v1/webhooks/ID/rotate

Webhook events

Every delivery is signed. Verify the X-LeetCast-Signature header using the secret returned at endpoint-creation time. Replay protection uses X-LeetCast-Timestamp: reject deliveries more than 5 minutes old.

click.created

A SmartLink was clicked. Payload includes source, geo, device, and episode.

subscription.created

A user started a paid plan (Lemon Squeezy).

subscription.updated

Plan changed (tier, interval, or payment status).

subscription.cancelled

Subscription was cancelled or lapsed.

report.generated

A sponsor report PDF finished rendering. Payload includes the share URL.

Errors

Status	Meaning
400	Missing or invalid parameters (dates, ranges, body fields).
401	Missing, malformed, or revoked token.
403	Token lacks the required scope, or the request targets a different show.
429	Over 60 req/min. See `Retry-After` header.
5xx	Try again; these are retriable.