API reference

Pull articles your newsroom has already written - full body HTML, images, metadata - into your own website, app or automation, on your schedule. Your content is never locked in. With a full-access key you can also commission work: an article, a batch, a research report or a domain audit.

Base URLhttps://api.mastheads.app

What a key can do depends on how it was made. Read only is the default and is the whole of the pull API; Full access adds the four doors that start work. That choice is fixed when the key is created - Full access & MCP.

1 · Get a key

Dashboard → Settings → Account → API access. Keys start with mh_live_. Details

2 · First pull

Call GET /v1/editions, then list one edition's articles.

3 · Sync incrementally

Store the newest created_at you have seen and pass it as ?since= on the next run.

Starting work instead

Create the key with Full access, then POST a brief and poll the job id it hands back. Same key over MCP. Full access & MCP

Read your content

Four, all GET, open to every key. A read spends nothing.

GET/v1/editionsEvery edition on your account, with per-status article counts.GET/v1/editions/{slug}/articlesAn edition's articles with full body HTML, oldest first, paginated.GET/v1/editions/{slug}/articles/{article_id}A single article by id, in the same shape the list returns.GET/v1/editions/{slug}/articles/{article_id}/imageThe article's featured image bytes, streamed with its own content type.

Start work

Four doors that commission work, and the poll that tells you where it got to. The four need a key created with Full access; the poll does not, so a read-only key can still watch.

POST/v1/editions/{slug}/articlesCommission one article on a domain. Answers 202 with a job id.POST/v1/editions/{slug}/articles/batchUp to 100 articles on one domain in a single call, with a refusal reason per row.POST/v1/editions/{slug}/researchCommission a research report on a domain. Answers 202 with a report id.POST/v1/editions/{slug}/auditCrawl a domain you have verified and audit what is there. Answers 202 with a crawl id.GET/v1/jobs/{job_id}Where an article job has got to, and which article it became.POST/v1/editions/{slug}/articles/{article_id}/publishPut a finished article live on the domain's connected site.

Getting your whole archive

The read endpoints hand you your articles one page at a time, which is what you want for a running integration. For a single file containing everything - every article as HTML and JSON, images and sources - use Download everything in Settings → Account. That is a dashboard job, not an API one: requests to /v1/exports answer 501 not_implemented.