Raindrop.io

Bookmarking service used as the podcast source queue.

Goals

A human-curated queue of articles to include in podcast episodes — something we can add to throughout the week by bookmarking articles, then have the pipeline drain automatically on each episode run. The key requirement was a durable, tag-based idempotency mechanism so the same article isn't used twice.

Effectiveness

Works well as a queue. The podcasted tag as an idempotency guard is clean and human-inspectable — we can see exactly what's been used, remove the tag to re-queue something, or add new bookmarks from any device. The REST API is simple and reliable.

What made it effective

• The tag-based queue pattern maps naturally onto how people actually use a bookmarking service. The pipeline drains untagged items; tagging is the acknowledgement. Simple and auditable.
• The REST API is straightforward with no surprising shape changes or envelope formats.
• Re-queueing an article is a single action (remove the podcasted tag) rather than a database operation.

Bonus utility

Raindrop's browser extension and mobile app mean the queue is easy to populate from anywhere — the pipeline input is effectively a reading list.

Friction / pain points / surprises

Paywalled and JS-rendered articles return partial or empty content. The pipeline fetches article text from the live URL at pipeline time. Articles behind a paywall or requiring JavaScript to render return either nothing or the paywall page. No warning — the pipeline just processes a thin article. The only mitigation is noticing during essay review that a source has no substance.

HTTP 200 with result: false silently disguises auth failures. When the API token is expired or invalid, Raindrop returns a 200 with {"result": false, "status": 401} in the body. resp.ok is true, data.items is undefined, and the code falls through to "no raindrops found" — masking the real error. The fix: check data.result === false explicitly and throw. This was responsible for a pipeline run that reported "no un-podcasted raindrops" despite 16,000 items in the queue.

Tagging must happen after a successful publish, not after successful generation. The podcasted tag is an idempotency guard — its purpose is to prevent an article from being used twice. If the pipeline tags articles before confirming that the episode was published, any failure between tagging and publishing silently burns those articles: they're excluded from future runs but never made it to air. Eight articles leaked this way. Fix: emit the tagged checkpoint only after the published checkpoint succeeds.

Tag accumulation creates noise. Raindrop accumulates one tag per distinct value ever applied — including tags created by pipeline bugs, tests, or one-off experiments. After enough runs, POST /api/v1/tags returns 527 tags, 324 of which had exactly one article. The tags panel becomes unusable. A cleanup script can bulk-delete singleton tags via the tag API, but there's no built-in decay mechanism.