Skip to content
Letterhead Letterhead Letterhead Help Center
Admin Tools

Curate content in bulk via API

Edit in CMS

Overview

Section titled “Overview”

The Letterhead API lets you push curated content into your account in bulk — many articles in a single request, rather than one call per article. Each curation in the batch names its own URL and which of your newsletters it should appear on. See Curate in bulk for the full request and response format.

Request shape

Section titled “Request shape”

Alongside your API key, send api: true and a curations array, where each entry accepts the same fields as the single-article Curate or update content endpoint:

  • url (required) — the article’s URL
  • channels — the newsletters this curation should appear on, by channel slug. Different curations in the same batch can target different channels.
  • title — saved exactly as you send it; this endpoint doesn’t fetch the page to generate one
  • excerpt, tags, overwriteTags — same behavior as the single-curation endpoint

Curating a URL you’ve already curated updates the existing curation instead of creating a duplicate — the same de-duplication the single-curation endpoint uses.

Batch size limit

Section titled “Batch size limit”

A single request accepts up to 500 curations. Internally, each curation fans out into one processing job per channel it targets (at least one job even if it names no channels), and the whole request is capped at 1,500 jobs total. So a batch of curations that each target several channels can hit the limit well before 500 curations — 400 curations naming 4 channels each, for example, would need 1,600 jobs, over the cap.

If a request would exceed the job limit, Letterhead rejects the whole batch with a 400 response naming the projected job count and the limit, so you know to split the request into smaller batches rather than guessing which curation pushed it over.

Response

Section titled “Response”

Accepted curations are queued for asynchronous processing. A 202 response reports how many curations were accepted and the total number submitted.

Use cases

Section titled “Use cases”
  • Backfilling a library of existing content across several newsletters at once
  • Publishing one story simultaneously across every newsletter it belongs on
  • Syncing curated content from an external CMS or feed on a recurring schedule

Next steps

Section titled “Next steps”

Still can’t find what you need? Contact support.