REST API Quickstart

Five steps from zero to a generated AI audio briefing.

Prerequisites

Looking for the MCP server instead? See the MCP quickstart →
1

Create an account

Sign up at listenbrief.com. Once you're in, navigate to Settings → API Keys in the dashboard. You'll create your first programmatic key in the next step.

2

Create an API key

Send a POST request to /api/v1/me/keys with a name and the scopes you need. The response includes your key — store it now, it is shown only once. 

curl -X POST https://listenbrief.com/api/v1/me/keys \
  -H "Authorization: Bearer <YOUR_SESSION_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My App",
    "scopes": ["read", "write"]
  }'

Response:

{
  "id": "key_01abc...",
  "name": "My App",
  "key": "lb_api_xxxxxxxxxxxxxxxxxxxx",
  "scopes": ["read", "write"],
  "created_at": "2024-01-15T10:00:00Z"
}
The key field is only returned once. Copy it to a safe place (e.g. a .env file) before continuing.
3

Create a briefing profile

A profile defines the topic interests and target length for a briefing. You'll reference its id when adding sources and generating briefings. 

curl -X POST https://listenbrief.com/api/v1/profiles \
  -H "Authorization: Bearer lb_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Tech",
    "interests": ["AI", "startups", "crypto"],
    "length_minutes": 5
  }'

Response:

{
  "id": "prof_01abc...",
  "name": "Daily Tech",
  "interests": ["AI", "startups", "crypto"],
  "length_minutes": 5,
  "created_at": "2024-01-15T10:01:00Z"
}

Save prof_01abc... — you'll use it in the next two steps.

4

Add a source

Attach an RSS feed (or any supported source type) to the profile. ListenBrief will pull content from this feed when generating a briefing. 

curl -X POST https://listenbrief.com/api/v1/sources \
  -H "Authorization: Bearer lb_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "rss",
    "url": "https://techcrunch.com/feed/",
    "name": "TechCrunch",
    "profile_id": "prof_01abc..."
  }'

Response:

{
  "id": "src_01abc...",
  "type": "rss",
  "url": "https://techcrunch.com/feed/",
  "name": "TechCrunch",
  "profile_id": "prof_01abc...",
  "created_at": "2024-01-15T10:02:00Z"
}
5

Generate a briefing

Trigger an on-demand briefing. The job is queued and processed asynchronously. Poll the status endpoint until status is "done", then fetch the MP3 audio URL.

Step 5a — Submit the job:

curl -X POST https://listenbrief.com/api/v1/briefings \
  -H "Authorization: Bearer lb_api_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"profile_id": "prof_01abc..."}'

Response:

{
  "job_id": "job_01abc...",
  "status": "queued"
}

Step 5b — Poll for completion:

# Replace job_01abc... with your actual job_id
curl https://listenbrief.com/api/v1/briefings/job_01abc... \
  -H "Authorization: Bearer lb_api_YOUR_KEY"

Repeat until "status": "done". Typical processing time is 30–90 seconds. Possible statuses: queued → processing → done (or failed).

Step 5c — Fetch the audio URL:

curl https://listenbrief.com/api/v1/briefings/job_01abc.../audio \
  -H "Authorization: Bearer lb_api_YOUR_KEY"

Response:

{
  "job_id": "job_01abc...",
  "audio_url": "https://cdn.listenbrief.com/briefings/job_01abc.../audio.mp3",
  "expires_at": "2024-01-16T10:03:00Z",
  "duration_seconds": 312
}
The audio_url is a signed CDN link valid for 24 hours. To receive a webhook when the job completes instead of polling, see the Webhooks guide.

Next Steps