API endpoint · v1

Start an article

Hands Mastheads one brief and returns immediately with a job id. The ten editorial desks write the article in the background, exactly as they would for a request made in the dashboard; poll the job for progress, and read the finished article through the list endpoint. Needs a key created with Full access.

POST/v1/editions/{slug}/articles

On this page

When to use it

To commission an article from your own tools - a spreadsheet, a button in your CMS, a script - instead of the dashboard.
When an AI assistant or an automation decides what to write, and Mastheads writes it with the same research and the same checks.
Send your own id with every request, so a retry after a timeout never pays for the same article twice.

Parameters

Param	In	Notes
slug	path	The domain UUID from GET /v1/editions. A segment that is not a UUID is a 404, and so is a domain that is not yours.
input	body	Required. What to write about, 1 to 2,000 characters.
id	body	Optional UUID of your own. It is the idempotency key: a repeat with the same id answers the job that already exists instead of starting a second one. Send one so a retry cannot spend twice.
language	body	Optional. Defaults to the domain's own language.
country	body	Optional. Defaults to the domain's own country.
settings	body	Optional. The same brief object the dashboard sends. Anything you leave out comes from the domain's saved Article Defaults - voice and style, length, sections, research and sources, images and brand - the same ones the dashboard and the newsroom use. A setting you send wins; inside voice and brand your fields win one by one, so sending a tone keeps the domain's banned words. It is validated, so a value out of bounds is a 422.

Request

curl -X POST https://api.mastheads.app/v1/editions/3f9c1e84-2b7a-4d6e-9c15-8a0d7e6b4f21/articles \
  -H "Authorization: Bearer mh_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"input": "Harbour redevelopment timetable", "id": "7c2b9f10-4a5d-4e88-9b31-6f0c2a1d5e73"}'

Response

202 Accepted

{
  "id": "7c2b9f10-4a5d-4e88-9b31-6f0c2a1d5e73",
  "status": "queued"
}

A repeat with an id you have already used is not an error and starts nothing: it answers that job's current progress instead, in the shape GET /v1/jobs/{id} returns.

Errors

Status	Code	When
401	invalid_key	Missing, invalid, or revoked API key.
401	account_closed	The account this key belongs to has been closed.
402	plan_required	The account's current plan does not include the content API. This is checked on the request, not only when the key was made.
503	unavailable	The plan or the data store could not be read. It refuses rather than guessing.
402	payment_required	A guard behind the door refused on plan or billing grounds. The message says which.
403	key_read_only	The key was created as Read only. A key's permission is fixed when it is made, so create a new key with Full access.
403	wrong_newsroom	A full-access key spends only in the newsroom its owner was in when it was created. If that person now acts in a different newsroom, create a new key there. A read-only key is not gated this way.
403	forbidden	A guard behind the door refused. The message says which.
404	not_found	No such domain on your account, or the path segment is not a UUID. Another tenant's domain is a 404, never a 403.
422	invalid_params	The body did not validate: a missing or over-long input, an id that is not a UUID, more than 100 rows, or two rows sharing an id.
429	rate_limited	Over this key's 20 paid actions an hour, or over its 120 requests/minute. Retry-After: 60, and nothing was started.

Every request needs a key - Authentication. The error shape and the full status table are on Rate limits & errors.