Reference

Endpoints

Anything not on this list answers 403 key_not_allowed to a key. It stays with a person.

On this page

How to read these pages#

Paths are relative to https://{your Brenzuri host}/api/v1. A path written {id} is a placeholder.
Scope is the scope the credential needs. Role is what the creating person must be allowed to do as well. Both are checked.
Credits says whether the route spends. Only starting an article or a column does.
Every route takes Authorization: Bearer <key>. Bodies are JSON with Content-Type: application/json, and the 2 MB limit of the proxy applies.
JSON responses carry Cache-Control: no-store.

Errors every route can return#

The per-route tables list only what is specific to the route.
Status	Code	Cause
401	`invalid_key`	The token is unknown, revoked, or has the wrong prefix for the path.
403	`scope_missing`	The credential does not carry the scope.
403	`forbidden`	The creating person’s role does not allow it.
404	`not_found`	No such object, or one the credential cannot see. A route that is not in this list also answers `not_found` to a bearer token, and is logged.
409	`workspace_paused`	Brenzuri has paused the workspace; writes are refused.
410	`workspace_deleted`	The workspace was deleted.
429	`rate_limited`	More than 60 requests a minute.

All 36 routes#

Method	Path	Scope	What
`POST`	`/api/v1/briefs`	`brief`	Create a brief
`GET`	`/api/v1/briefs/{id}`	`read`	Read a brief
`PATCH`	`/api/v1/briefs/{id}`	`brief`	Change a brief
`POST`	`/api/v1/briefs/{id}/estimate`	`brief`	Ask what starting the brief would cost, and whether the credential may afford it
`POST`	`/api/v1/articles`	`generate`	Start an article from a brief
`POST`	`/api/v1/articles/{id}/languages`	`generate`	Add language versions to an article that is finished
`GET`	`/api/v1/articles`	`read`	List the articles this credential can see, newest change first
`GET`	`/api/v1/articles/{id}`	`read`	Read one article with its text, claims, sources, quality checks, versions and label
`POST`	`/api/v1/articles/{id}/claims/{claimId}/sources`	`edit`	Add a source to a claim
`POST`	`/api/v1/articles/{id}/paragraphs/{n}/regenerate`	`edit`	Rewrite one paragraph from the claims it carries
`PUT`	`/api/v1/articles/{id}/units/{n}`	`edit`	Replace the text of one unit: a paragraph, heading or list item with `text`, a table row with `cells`
`PUT`	`/api/v1/articles/{id}/title`	`edit`	Change the title
`PUT`	`/api/v1/articles/{id}/deck`	`edit`	Change the deck, the standfirst under the title
`DELETE`	`/api/v1/articles/{id}/links/{linkId}`	`edit`	Remove one internal link, one of the `internalLinks` of the article
`POST`	`/api/v1/articles/{id}/structure`	`edit`	Change the shape of the text: insert a paragraph, heading, list item or table row, remove a unit, or move one up or down
`POST`	`/api/v1/articles/{id}/archive`	`edit`	Archive an article
`GET`	`/api/v1/jobs/{id}`	`read`	Read where a job is now: its status, the step it is on and every step with its status
`GET`	`/api/v1/jobs/{id}/events`	`read`	Follow a job as a server-sent event stream
`POST`	`/api/v1/jobs/{id}/steps/{stepId}/retry`	`edit`	Run the failed step again
`POST`	`/api/v1/jobs/{id}/steps/{stepId}/skip`	`edit`	Skip a failed optional step (`seo`, `illustrate`, or a language version step such as `write-es`) and let the job carry on
`POST`	`/api/v1/jobs/{id}/cancel`	`edit`	Cancel a job
`GET`	`/api/v1/sites`	`read`	List the sites this credential can see
`GET`	`/api/v1/sites/{siteID}`	`read`	Read one site: its voice, plan of columns, what is being written, and a summary of its house style
`POST`	`/api/v1/sites/{siteID}/analyze`	`edit`	Read the site again
`POST`	`/api/v1/sites/{siteID}/topics/check`	`brief`	Count the independent origins for a topic before committing to a brief
`GET`	`/api/v1/sites/{siteID}/topics/{topicId}`	`read`	Read one column: the topic, its origins, and the sources you have added
`POST`	`/api/v1/sites/{siteID}/topics/{topicId}/write`	`generate`	Write a column
`POST`	`/api/v1/sites/{siteID}/topics/{topicId}/sources`	`edit`	Add a source to a column: a page to read, a note you wrote, or a copy of another source
`GET`	`/api/v1/sites/{siteID}/connections`	`read`	List the connection that delivers this site’s articles, so you can find the `connectionId` that deliver needs
`POST`	`/api/v1/articles/{id}/export`	`export`	Render the article as a file
`GET`	`/api/v1/exports/{exportId}`	`export`	Download an export made with the route above
`POST`	`/api/v1/articles/{id}/deliver`	`export`	Deliver the article through a connection
`GET`	`/api/v1/sites/{siteID}/house-style`	`read`	Read the site’s illustration style: the one a person confirmed, and a proposal waiting for a person to look at it
`GET`	`/api/v1/sites/{siteID}/house-style/images/{imageID}`	`read`	Download one of the reference images the style was read from
`GET`	`/api/v1/articles/{id}/illustration`	`read`	Download the picture on an article
`POST`	`/api/v1/articles/{id}/illustration/regenerate`	`edit`	Make a new picture for an article that has one, in the site’s style

What a key cannot call#

Everything else answers 403 key_not_allowed, even with every scope. That includes approving and republishing, keeping a flag, comments, writing an article again, rescoring, voices, Beats and their candidates, schedules, creating, pausing or deleting a site, changing the house style, creating, changing, testing, listing or retrying a connection (a key reads one site’s connection with GET /sites/{siteID}/connections), site delivery, billing and credits, usage, /me, and the developer pages that make keys, agents and webhooks.