Publish an article

The fifth door, and the heaviest: this one puts the article on a live site where your own readers see it. It runs the same guards as pressing Publish in the dashboard, and it is recorded against the person whose key it is.

POST/v1/editions/{slug}/articles/{article_id}/publish

Parameters

Param	In	Notes
slug	path	The domain UUID. The article must belong to this domain: another domain's article is a 404 even when you own both.
article_id	path	The article UUID. A stale or deleted id is a 404 and costs nothing against your hourly room.
section_slug	body	Optional, and the body itself is optional. The section to file the post under, as in the dashboard's publish dialog. Omit it to publish with no section picked.

Request

curl -X POST https://api.mastheads.app/v1/editions/3f9c1e84-2b7a-4d6e-9c15-8a0d7e6b4f21/articles/a1d4c7b2-5e83-4f19-b06c-2d9f8e3a7c54/publish \
  -H "Authorization: Bearer mh_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"section_slug": "news"}'

Response

200 OK

{
  "ok": true,
  "published_url": "https://thebristolledger.com/harbour-works-overrun-by-two-years"
}

This one answers when the work is done, not with a job id: there is nothing to poll. It costs one of the twenty paid actions an hour, and no article allowance - the article was already paid for when it was written.

Field	Type	Notes
published_url	string	Where the post now lives on your site.

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.
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.
404	not_found	No such domain or article on your account, the article belongs to a different domain, or a path segment is not a UUID.

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