Reference

Endpoints: briefs

Briefs never spend credits. The scope is brief, plus read for reading one back.

On this page

A brief asks for one article. The routes here never spend credits. To count independent origins for a topic before writing a brief, use `POST /sites/{siteID}/topics/check`, which also needs only the brief scope.

POST`/api/v1/briefs`

Scopebrief
Credits free
Role edit (Owner, Editor, Writer)

Create a brief. Every field is optional; what is left out takes the default shown on Brief. A key or an agent bound to a site gets that site when siteId is left out.

Body

Name	Type	Description
`topic`	`string`	What the article is about. Not checked for being non-empty at this point.
`angle`	`string`	What the piece should focus on.
`siteId`	`string`	The site. A site-bound credential can only name its own.
`brandId`	`string`	A voice profile. Unknown ids are 404.
`purpose`	`string`	`news`, `explainer`, `background`, `roundup`, `press` or `blog`.
`audience`	`string`	Who it is for.
`region`	`string`	Up to 60 characters.
`language`	`string`	One language code, or the article and its language versions joined by `+`, as `en+es+de`: the first code is the article, the others are versions of it. With `+` each code must be one of the 22 supported languages and appear once.
`tone`	`string`	`neutral`, `explanatory`, `formal` or `conversational`.
`length`	`string`	`short`, `standard` or `long`.
`targetWords`	`integer`	Clamped to 300–3000.
`structure`	`string`	`ibc`, `list` or `qa`.
`keywords`	`string[]`	Keywords for the SEO fields.
`mustAppear`	`string[]`	Up to 10 phrases, 200 characters each.
`useUrls`	`string[]`	Pages to read first.
`excludeDomains`	`string[]`	Domains to leave out.
`preferDomains`	`string[]`	Domains to prefer.
`illustration`	`string`	`generate`, `upload` or `none`.
`seo`	`boolean`	Whether to write the SEO fields.

Response

200The Brief, with defaults filled in. It is created, not started; nothing is spent.

JSON

{
  "id": "5D2E8A14-7B3C-4F69-A0D1-9C46E3B7F208",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "topic": "Ferry operators agree on a single timetable for the northern route",
  "angle": "What changes for commuters from November",
  "useUrls": [],
  "excludeDomains": [],
  "purpose": "news",
  "audience": "",
  "region": "Global",
  "language": "en",
  "tone": "neutral",
  "length": "standard",
  "targetWords": 900,
  "structure": "ibc",
  "keywords": [],
  "mustAppear": [
    "the November start date"
  ],
  "preferDomains": [],
  "illustration": "none",
  "seo": true
}

Errors

Status	Code	When
404	not_found	The `brandId` or `siteId` does not exist or is not visible to this credential.
400	validation	The body could not be read.
422	invalid_language	A code in a `+` list is not a supported language, appears twice, or is empty, or the value has a space in it.

curl -X POST "$BRENZURI_URL/api/v1/briefs" \
  -H "Authorization: Bearer $BRENZURI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Ferry operators agree on a single timetable for the northern route",
    "angle": "What changes for commuters from November",
    "purpose": "news",
    "length": "standard",
    "mustAppear": [
      "the November start date"
    ],
    "illustration": "none"
  }'

Example request

GET`/api/v1/briefs/{id}`

Scoperead
Credits free

Read a brief.

Path

Name	Type	Description
`id`	`string`	The brief id.

Response

200The Brief.

JSON

{
  "id": "5D2E8A14-7B3C-4F69-A0D1-9C46E3B7F208",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "topic": "Ferry operators agree on a single timetable for the northern route",
  "angle": "What changes for commuters from November",
  "useUrls": [],
  "excludeDomains": [],
  "purpose": "news",
  "audience": "",
  "region": "Global",
  "language": "en",
  "tone": "neutral",
  "length": "standard",
  "targetWords": 900,
  "structure": "ibc",
  "keywords": [],
  "mustAppear": [
    "the November start date"
  ],
  "preferDomains": [],
  "illustration": "none",
  "seo": true
}

Errors

Status	Code	When
404	not_found	No such brief, or it belongs to a site this credential cannot see.

curl "$BRENZURI_URL/api/v1/briefs/$BRIEF_ID" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Example request

PATCH`/api/v1/briefs/{id}`

Scopebrief
Credits free
Role edit

Change a brief. Send only the fields to change; the body is the same as for creating one.

Path

Name	Type	Description
`id`	`string`	The brief id.

Body

Name	Type	Description
`any field of POST /briefs`	`various`	Fields left out are not changed.

Response

200The changed Brief.

JSON

{
  "id": "5D2E8A14-7B3C-4F69-A0D1-9C46E3B7F208",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "topic": "Ferry operators agree on a single timetable for the northern route",
  "angle": "What changes for commuters from November",
  "useUrls": [],
  "excludeDomains": [],
  "purpose": "news",
  "audience": "",
  "region": "Global",
  "language": "en",
  "tone": "neutral",
  "length": "long",
  "targetWords": 1400,
  "structure": "ibc",
  "keywords": [],
  "mustAppear": [
    "the November start date"
  ],
  "preferDomains": [],
  "illustration": "none",
  "seo": true
}

Errors

Status	Code	When
404	not_found	No such brief, brand or site.
422	invalid_language	The new `language` is not valid. See POST /briefs.

curl -X PATCH "$BRENZURI_URL/api/v1/briefs/$BRIEF_ID" \
  -H "Authorization: Bearer $BRENZURI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "length": "long",
    "targetWords": 1400
  }'

Example request

POST`/api/v1/briefs/{id}/estimate`

Scopebrief
Credits free

Ask what starting the brief would cost, and whether the credential may afford it. The balance is never returned.

Path

Name	Type	Description
`id`	`string`	The brief id.

Query

Name	Type	Description
`articleId`	`string`	Price writing this article again instead of a first write. For an article written from the brief, only the language versions it does not have yet are counted on top of the article; for a language version, only that version. The article must have been written from this brief.

Response

200The Estimate.

JSON

{
  "credits": 1,
  "parts": [
    {
      "label": "Article",
      "credits": 1,
      "kind": "article"
    }
  ],
  "steps": [
    {
      "id": "find",
      "name": "Searching your domains",
      "estMs": 14200
    },
    {
      "id": "group",
      "name": "Grouping by origin",
      "estMs": 6100
    },
    {
      "id": "read",
      "name": "Reading one page per origin",
      "estMs": 39400
    },
    {
      "id": "check",
      "name": "Checking claims across origins",
      "estMs": 30800
    },
    {
      "id": "write",
      "name": "Writing",
      "estMs": 48000
    },
    {
      "id": "seo",
      "name": "Writing the SEO fields",
      "estMs": 4000
    },
    {
      "id": "qa",
      "name": "Reading the finished text back",
      "estMs": 9000
    }
  ],
  "enough": true
}

Errors

Status	Code	When
404	not_found	No such brief, or `articleId` is not an article written from it.
422	invalid_language	The brief’s `language` is not valid. A brief made or changed through the API cannot be saved with one.

enough is false when the trial has ended, the balance is below credits, or, for a key or an agent, today’s spend plus credits would pass its daily cap.
credits is the article’s cost plus 1 for each language version, and parts lists them. The steps list includes seo only when the brief asks for it and illustrate only when illustration is generate, and the three steps of each language version after the article’s steps. See Write in several languages.

curl -X POST "$BRENZURI_URL/api/v1/briefs/$BRIEF_ID/estimate" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Example request