API Access

Go to Settings in your dashboard and scroll to the API Keys section. Click 'Generate key', give it a descriptive name (e.g. 'Production pipeline'), and copy the key immediately — it's shown only once. Keys use the pl_ prefix for easy identification.

Include your API key as a Bearer token in the Authorization header: curl -H "Authorization: Bearer pl_your_key_here" \ https://punchline.gg/api/episodes

The programmatic upload flow mirrors the web UI: Step 1 — Create upload intent: curl -X POST https://punchline.gg/api/episodes/upload-intent \ -H "Authorization: Bearer pl_..." \ -H "Content-Type: application/json" \ -d '{"title": "Episode 42", "fileName": "ep42.mp3", "fileSize": 52428800, "fileType": "audio/mpeg", "ownershipConfirmed": true}' Step 2 — Upload the file to the returned storage URL via TUS protocol. Step 3 — Finalise: curl -X PATCH https://punchline.gg/api/episodes/{episodeId}/upload-complete \ -H "Authorization: Bearer pl_..."

Trigger transcription: curl -X POST https://punchline.gg/api/episodes/{episodeId}/transcribe \ -H "Authorization: Bearer pl_..." Poll status until 'transcribed', then trigger analysis: curl -X POST https://punchline.gg/api/episodes/{episodeId}/analyse \ -H "Authorization: Bearer pl_..." Poll status until 'completed'.

Retrieve your clip plan as JSON: curl https://punchline.gg/api/episodes/{episodeId}/export \ -H "Authorization: Bearer pl_..." Or as CSV: curl "https://punchline.gg/api/episodes/{episodeId}/export?format=csv" \ -H "Authorization: Bearer pl_..."

API key requests have generous rate limits: 20 analyses/minute, 10 upload intents/minute, 60 status polls/minute. Each key is rate-limited independently. If you hit a limit, you'll receive a 429 response with a Retry-After header.

You can have up to 10 active API keys. Revoke compromised keys immediately from Settings — revoked keys return 401 on all subsequent requests. Key usage (last used date) is tracked for auditing.