Mastheads API (v1)
A read-only API for pulling your articles into your own website, app, or automation (cron, n8n, Zapier-style tools). Your code asks for anything new on its own schedule and imports it — no CMS connection required.
Authentication
Generate an API key in your dashboard under Settings → Account → API access. Send it with every request. Keys are server-side secrets: never ship one in browser code or a public repo. If a key leaks, revoke it in Settings — it dies instantly.
curl https://api.mastheads.app/v1/editions \
-H "Authorization: Bearer mh_live_your_key_here"An X-Api-Key header works too. Keys work while your subscription or trial is active; after it ends, the API returns 403 and your content stays downloadable from the dashboard.
Endpoints
| Endpoint | Returns |
|---|---|
| GET /v1/editions | Your editions with article counts |
| GET /v1/editions/{slug}/articles | Articles with full body HTML (paginated) |
| GET /v1/editions/{slug}/articles/{id} | One article |
| GET /v1/editions/{slug}/articles/{id}/image | The article's featured image (webp) |
| POST /v1/exports | Start a bulk export (zip with WordPress WXR + Ghost JSON + Markdown + HTML + images) |
| GET /v1/exports/{id} | Export status |
| GET /v1/exports/{id}/download | The finished zip (available 24 hours) |
Incremental pulls
Pass since (ISO-8601) to get only articles created after your last pull. Articles come oldest-first, so store the newest created_at you have seen and pass it next time.
curl "https://api.mastheads.app/v1/editions/my-edition/articles?since=2026-07-05T00:00:00Z&limit=50" \
-H "Authorization: Bearer mh_live_your_key_here"Parameters: since (exclusive), status (draft or published), limit (max 100), offset.
{
"total": 142,
"limit": 50,
"offset": 0,
"articles": [
{
"id": 8931,
"title": "Example headline",
"status": "published",
"section": "finance",
"byline": "Jordan Avery",
"intro": "<p>...</p>",
"body": "<p>...</p>",
"conclusion": "<p>...</p>",
"meta_title": "Example headline",
"meta_description": "...",
"tags": ["example", "finance"],
"image_url": "https://.../hero.webp",
"created_at": "2026-07-05T08:12:00Z",
"published_at": "2026-07-05T09:00:00Z"
}
]
}Bulk export
# start it
curl -X POST https://api.mastheads.app/v1/exports \
-H "Authorization: Bearer mh_live_your_key_here" \
-H "Content-Type: application/json" \
-d '{"scope": "account"}'
# -> {"id": "3f2a...", "status": "queued"}
# poll it, then download
curl https://api.mastheads.app/v1/exports/3f2a... -H "Authorization: Bearer ..."
curl -o export.zip https://api.mastheads.app/v1/exports/3f2a.../download -H "Authorization: Bearer ..."Scope account or edition (with an edition slug). One export runs at a time; finished zips expire after 24 hours.
Limits and errors
120 requests/minute per key; 4 export creations/hour. Errors are JSON: {"error": {"code", "message"}} — 401 invalid key, 403 subscription ended, 404 not found, 409 export already running, 410 export expired, 429 rate limited (with a Retry-After header). Reads never consume your article quota.