Episode archive

GET https://api.particle.pro/v1/podcasts/episodes/archive
GET https://api.particle.pro/v1/podcasts/episodes/archive/download?period=2026-09
GET https://api.particle.pro/v1/podcasts/episodes/archive/stream?period=2026-09

​

What’s in it

• Every transcribed episode. An episode is in the archive once it has a transcript, with its segments and clips if it has them.
• Filed by publication date. The archive is divided into days and months of UTC publication date. An episode published in March 2024 is in 2024-03, whenever we ingested it.
• One episode per line, in publication order, as the stream’s episode object with include=all. Fields that the stream adds over time appear in the archive within its refresh cycle.
• Every file is a complete snapshot of its period. When you download a day or month again, replace your copy of it. An episode missing from the new copy was removed or moved to another day.

​

Load the archive

1. List what there is. The listing gives every month with its days, their episode counts and sizes, and a version for each.
   curl -s -H "X-API-Key: $PARTICLE_API_KEY" \
     https://api.particle.pro/v1/podcasts/episodes/archive
   
   {
     "as_of": "2026-10-01T01:30:05Z",
     "stream_since": "2026-10-01T01:20:05Z",
     "months": [
       {
         "month": "2026-09",
         "episodes": 1234,
         "bytes": 56789012,
         "version": "5f0c…",
         "updated_at": "2026-10-01T01:41:12Z",
         "days": [
           { "date": "2026-09-01", "episodes": 41, "bytes": 1890123, "version": "a91e…", "updated_at": "2026-10-01T01:33:40Z" }
         ]
       }
     ]
   }
   
2. Download the months or days you want. Requests are independent, so download several in parallel.
   curl -s -H "X-API-Key: $PARTICLE_API_KEY" -o 2026-09.jsonl.gz \
     "https://api.particle.pro/v1/podcasts/episodes/archive/download?period=2026-09"
   zcat 2026-09.jsonl.gz | head -1 | jq '{id, title, published_at}'
   
3. Follow the stream from stream_since. The archive holds every change recorded up to as_of. Open the stream from stream_since, just before it, so nothing falls between the two. Some episodes will arrive twice; deduplicate on the episode id, as the stream already requires.
   GET /v1/podcasts/episodes/stream?milestone=fully_ingested&include=all&since=2026-10-01T01:20:05Z
   

​

Keep your copy current

curl -s -H "X-API-Key: $PARTICLE_API_KEY" \
  "https://api.particle.pro/v1/podcasts/episodes/archive?updated_since=2026-10-01T01:30:05Z"

​

Downloads

• Resuming. A day supports Range requests, so curl -C - resumes it. A month does not. On an unreliable connection, download days.
• Unchanged files. A full download’s ETag is the period’s version; a download narrowed with include has an ETag of its own. Send the ETag you received back in If-None-Match to get 304 Not Modified when nothing changed.
• Less data. include keeps only the relations you name, from transcript, segments and clips; the default is all of them, unlike the stream, where it is none. Every other field is unchanged. A narrowed download is assembled as it is sent, so it is slower and has no Content-Length or Range.

import gzip, json

with gzip.open("2026-09.jsonl.gz", "rt") as f:
    for line in f:  # lines can be several megabytes
        episode = json.loads(line)
        upsert(episode["id"], episode)

​

Replay over Server-Sent Events

event: episode
data: {"cursor":"MTcyNjE…","episode":{"id":"…","title":"…","transcript":{…}}}

event: complete
data: {"period":"2026-09","episodes":1234}