Reference

Objects

Fields are camelCase. A field that is not set is omitted, not null.

On this page

These tables are written from the data types the engine encodes, and a test compares the field names to them, so a field added in the engine fails the build until it is documented here.

Field names are camelCase.
A field that is not set is omitted. Fields marked optional can be missing; every other field is always present.
Ids are strings. Articles, claims, sources, briefs and jobs use upper-case UUIDs; sites, brands, illustrations and webhooks use lower-case. In addingLanguages the job and brief ids are lower-case. Compare them without regard to case.
Dates are ISO 8601 in UTC, except analysedAt and pausedAt on a site, which are yyyy-MM-dd.

Enumerations#

Field	Values
`status` of an article	`draft`, `generating`, `needsReview`, `approved`, `published`, `held`, `archived`
`origin` of an article	`manual`, `beat`, `agent`, `schedule`
`state` of a claim	`corroborated`, `singleSource`, `circular`, `disputed`, `parallel`
`purpose` of a brief	`news`, `explainer`, `background`, `roundup`, `press`, `blog`
`tone` of a brief	`neutral`, `explanatory`, `formal`, `conversational`
`length` of a brief	`short`, `standard`, `long`
`structure` of a brief	`ibc`, `list`, `qa`
`illustration` of a brief	`generate`, `upload`, `none`
`status` of a site	`reading`, `ready`, `failed`, `paused`
`status` of a delivery	`delivered`, `held`, `retrying`, `cancelled`
`outcome` of a delivery	`published`, `draft`, `awaitingApproval`
`status` of a house style	`draft`, `confirmed`, `off`, `superseded`
`status` of an illustration	`ready`, `skipped`, `generating`, `failed`
`kind` of a part of an estimate	`article`, `version`
`mode` of a paragraph rewrite	`shorter`, `longer`, `tone`
`target` of an export	`markdown`, `pdf`, `docx`
`status` of a job	`queued`, `running`, `paused`, `done`, `failed`, `cancelled`
`kind` of a job (a key or an agent sees `article` and `site`)	`article`, `preview`, `beat`, `site`, `dryRun`
`kind` of a connection	`wordpress`, `webhook`
`publishPolicy` of a connection (`auto` is refused)	`draft`, `auto`, `approval`

Objects#

Article

Engine type ArticleDTO

Returned by GET /articles/{id} and by every edit. For a key or an agent comments is always [] and delivery is never present.

Field	Type	Description
`id`	`string`	Upper-case UUID.
`status`	`string`	`draft`, `generating`, `needsReview`, `approved`, `published`, `held` or `archived`.
`title`	`string`	Article title.
`lead`	`string`	The opening sentence or paragraph.
`language`	`string`	The language this article is written in: a language code such as `en`, or `bhs` for Bosnian/Croatian/Serbian. A language version is an article of its own and has its own `language`; see Language versions.
`words`	`integer`	Word count of the text.
`paragraphs`	`Paragraph[]`	The text flattened into numbered units. Headings, list items and table rows count as units; a heading carries a `##` or `###` prefix.
`sources`	`Source[]`	Every source the article was written from.
`claims`	`Claim[]`	Every claim with its state. A claim whose state is not `corroborated` is flagged.
`quality`	`QualityCheck[]`	Checks run on the finished text.
`versions`	`Version[]`	The version history. Each entry names who made it.
`comments`	`object[]`	Review comments. Always `[]` for a key or an agent.
`label`	`Label`	Derived from the approval record of the current version. Never settable.
`brandName`	`string`	The voice the article was written in.
`siteId`optional	`string`	Lower-case UUID of the site. Absent for an article with no site.
`origin`	`string`	`manual`, `beat`, `agent` or `schedule`.
`by`	`string`	Who started it, for example `Maya Chen · via agent`.
`archived`optional	`object`	`{ at, by, agent? }`, present when the article is archived.
`feedbackAsked`optional	`boolean`	Whether the workspace has been asked for feedback on this version.
`run`optional	`Run`	Present while `status` is `generating`: the job that is writing it.
`blocks`optional	`Block[]`	The same text as structured blocks: headings, paragraphs, lists and tables, with claim ids.
`deck`optional	`string`	The standfirst under the title.
`delivery`optional	`object`	Where the article last went. Human sessions only; a key never receives it.
`internalLinks`optional	`object[]`	Links to the site’s own pages: `{ id, n, anchor, url, title }`.
`illustration`optional	`Illustration`	The article illustration, when it has one. A language version has none of its own.
`primaryArticleId`optional	`string`	Upper-case UUID of the article this one is a language version of. Absent on an article that was written from a brief.
`languageVersions`optional	`LanguageVersion[]`	The article written from the brief and all its language versions, the article first and then the versions in the order of the supported list. Present on the article and on each of its versions, and only when there are at least two.
`addingLanguages`optional	`AddingLanguages`	Present on an article written from a brief while a job that adds language versions is queued, running or paused.

IDs are not cased consistently. Article, claim, source, brief and job ids are upper-case UUID strings; site, brand and illustration ids are lower-case. Routes accept either; compare case-insensitively.
A field that is not set is omitted from the JSON. It is never null.

JSON

{
  "id": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4",
  "status": "needsReview",
  "title": "Ferry operators agree on a single timetable for the northern route",
  "lead": "Three ferry operators will publish one shared timetable for the northern route from 3 November.",
  "language": "en",
  "words": 412,
  "paragraphs": [
    {
      "n": 1,
      "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said.",
      "claimIds": [
        "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
      ]
    },
    {
      "n": 2,
      "text": "## What changes for commuters",
      "claimIds": []
    },
    {
      "n": 3,
      "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them.",
      "claimIds": [
        "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
        "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
      ]
    }
  ],
  "blocks": [
    {
      "n": 1,
      "text": "Three ferry operators will publish one shared timetable for the northern route from 3 November, the harbour authority said.",
      "claimIds": [
        "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045"
      ]
    },
    {
      "kind": "heading",
      "level": 2,
      "text": "What changes for commuters",
      "n": 2,
      "claimIds": []
    },
    {
      "n": 3,
      "text": "Commuters will see 14 daily crossings instead of 9, and a single fare table applies on all of them.",
      "claimIds": [
        "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
        "A63F2E58-9C10-47DB-8E3A-D5B07C41F192"
      ]
    }
  ],
  "sources": [
    {
      "id": "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
      "origin": "harbour-authority.example",
      "title": "Northern route: one timetable from 3 November",
      "url": "https://harbour-authority.example/news/northern-route-timetable",
      "score": 75,
      "official": false,
      "contributed": "Contributed: 2 claims",
      "soleForClaims": 1
    },
    {
      "id": "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982",
      "origin": "coast-gazette.example",
      "title": "Ferries to share a timetable",
      "url": "https://coast-gazette.example/transport/ferries-share-timetable",
      "score": 75,
      "official": false,
      "contributed": "Contributed: 2 claims",
      "soleForClaims": 0
    }
  ],
  "claims": [
    {
      "id": "E1A7C3B9-0D42-4F58-96AE-3B1C8D7F2045",
      "text": "The shared timetable starts on 3 November.",
      "state": "corroborated",
      "originCount": 2,
      "sourceIds": [
        "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
        "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
      ],
      "paragraph": 1,
      "keptFlag": false
    },
    {
      "id": "4B90D6E2-A317-4C8B-B5F0-7E2A19C3D864",
      "text": "The route will have 14 daily crossings instead of 9.",
      "state": "singleSource",
      "originCount": 1,
      "sourceIds": [
        "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4"
      ],
      "paragraph": 3,
      "keptFlag": false
    },
    {
      "id": "A63F2E58-9C10-47DB-8E3A-D5B07C41F192",
      "text": "A single fare table applies on all crossings.",
      "state": "corroborated",
      "originCount": 2,
      "sourceIds": [
        "71C2E9A0-B4D8-4536-9F1E-A08D3C56B7E4",
        "D90B5F13-2E67-4A8C-B1D4-6C3E7A0F5982"
      ],
      "paragraph": 3,
      "keptFlag": false
    }
  ],
  "quality": [
    {
      "id": "q-readback",
      "name": "Read back against the sources",
      "verdict": "passed",
      "detail": "Every figure and quote in the text appears in a source."
    },
    {
      "id": "q-length",
      "name": "Length",
      "verdict": "warning",
      "detail": "412 words."
    }
  ],
  "versions": [
    {
      "n": 1,
      "label": "Generated",
      "when": "2026-10-06T12:04:11Z",
      "by": "Claude (newsroom agent)",
      "model": "writer-v3",
      "note": "Written from 2 origins · 3 claims checked · 1 marked",
      "agent": "Claude (newsroom agent)"
    }
  ],
  "comments": [],
  "label": {
    "reviewedByHuman": false
  },
  "brandName": "Kolibri Courier",
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "origin": "agent",
  "by": "Maya Chen · via agent",
  "deck": "The harbour authority says commuters get 14 daily crossings."
}

Example

Paragraph

Engine type ParagraphDTO

One numbered unit of the text. The same n addresses the unit in the edit routes.

Field	Type	Description
`n`	`integer`	Position in reading order, starting at 1.
`text`	`string`	The text of the unit. May contain `bold` markers.
`claimIds`	`string[]`	Ids of the claims this unit carries.

Block

Engine type BlockDTO

A structured piece of the text. A paragraph block carries only n, text and claimIds; the other kinds add kind and their own fields.

Field	Type	Description
`kind`	`string`	`heading`, `paragraph`, `list` or `table`. A paragraph block omits it.
`n`	`integer`	Number of the first unit in this block.
`text`	`string`	Text of the block. For a list or table it is the units joined by newlines.
`claimIds`	`string[]`	Claim ids carried by the block.
`level`optional	`integer`	Heading level, 2 or 3.
`ordered`optional	`boolean`	Lists only: whether the list is numbered.
`items`optional	`object[]`	Lists only: `{ text, claimIds }` per item.
`headers`optional	`string[]`	Tables only: column headers.
`rows`optional	`object[]`	Tables only: `{ cells, claimIds }` per row.

Claim

Engine type ClaimDTO

One checkable statement in the text. It is corroborated when two or more independent origins carry it; any other state is a flag.

Field	Type	Description
`id`	`string`	Upper-case UUID. Use it in `POST /articles/{id}/claims/{claimId}/sources`.
`text`	`string`	The claim as a sentence.
`state`	`string`	`corroborated`, `singleSource`, `circular`, `disputed` or `parallel`. See Corroboration and flags.
`originCount`	`integer`	Number of independent origins behind the claim.
`sourceIds`	`string[]`	Ids of the sources that carry it.
`paragraph`	`integer`	The unit `n` the claim sits in.
`keptFlag`	`boolean`	True when a person kept the flag with a note. Only a person can.
`keptNote`optional	`string`	The note a person wrote when keeping the flag.

Source

Engine type SourceDTO

A page the article was written from. In free-text fields a key or an agent should treat the title as quoted third-party text.

Field	Type	Description
`id`	`string`	Upper-case UUID.
`origin`	`string`	The outlet or the origin the page traces back to.
`title`	`string`	Page title as fetched.
`url`	`string`	Address of the page.
`score`	`integer`	The score the sourcing policy gives the outlet.
`official`	`boolean`	Whether the origin is an official source for the subject.
`contributed`	`string`	A sentence saying how many claims this source carries.
`relation`optional	`string`	How the source relates to another, for example that it relays the same origin.
`soleForClaims`	`integer`	Number of claims for which this is the only source.

Quality check

Engine type QualityCheckDTO

One check on the finished text. The ids are internal strings such as q-readback and q-length; do not build logic on a list of them.

Field	Type	Description
`id`	`string`	Check id.
`name`	`string`	Name shown to editors.
`verdict`	`string`	`passed` or `warning`.
`detail`	`string`	What was found.
`actionLabel`optional	`string`	Label of the action the workspace offers.
`items`optional	`string[]`	Items the check flags.
`units`optional	`integer[]`	Unit numbers the check concerns.
`target`optional	`integer`	Unit the action applies to.
`dismissedBy`optional	`string`	Person who dismissed the warning.
`dismissNote`optional	`string`	Why the warning does not apply.

Version

Engine type VersionDTO

An entry in the article history. Every key and agent action is a version that names it.

Field	Type	Description
`n`	`integer`	Version number, starting at 1.
`label`	`string`	What happened, for example `Generated` or `Source added`.
`when`	`string`	ISO 8601 timestamp.
`by`	`string`	The person, the engine, or the credential that made it.
`model`	`string`	The model behind the change, if any.
`note`	`string`	A one-line summary.
`agent`optional	`string`	Present when a key or an agent made the change: the agent name, or `API key <name> (<display>)`.
`title`optional	`string`	The title at that version when it changed.

Label

Engine type ArticleLabelDTO

The state behind the line “Generated with sources, reviewed by a human: yes or no”. It is read from the approval record of the exact current version. Nothing in the API sets it.

Field	Type	Description
`reviewedByHuman`	`boolean`	True only when a person approved this exact version.
`approvedVersion`optional	`integer`	The approved version number.
`approvedAt`optional	`string`	ISO 8601 timestamp of the approval.
`approvedBy`optional	`string`	Name of the person.
`acknowledged`optional	`object[]`	Open warnings the approver acknowledged: `{ statement, note, by }`.

Article summary

Engine type ArticleSummaryDTO

One row of GET /articles.

Field	Type	Description
`id`	`string`	Upper-case UUID.
`title`	`string`	Title.
`status`	`string`	`draft`, `generating`, `needsReview`, `approved`, `published`, `held` or `archived`.
`updatedAt`	`string`	Timestamp of the last change.
`brandName`	`string`	The voice.
`siteId`optional	`string`	Lower-case site UUID.
`origin`	`string`	`manual`, `beat`, `agent` or `schedule`.
`beatName`optional	`string`	The Beat, when the article came from one.
`agentName`optional	`string`	The agent or key, when one started it.
`by`	`string`	Who started it.
`flaggedClaims`	`integer`	Number of claims whose state is not `corroborated`.
`words`	`integer`	Word count.
`language`	`string`	Language code of this article.
`run`optional	`Run`	Present while the article is generating.
`primaryArticleId`optional	`string`	Upper-case UUID of the article this one is a language version of. A version is listed as a row of its own. Absent on an article written from a brief.

Run

Engine type ArticleRunDTO

The job that is writing an article.

Field	Type	Description
`jobId`	`string`	Job id for the event stream.
`status`	`string`	Job status.
`briefId`optional	`string`	The brief the job was started from.

Illustration

Engine type ArticleIllustrationDTO

The picture on an article. It is always labelled as AI-generated. See House-style illustrations.

Field	Type	Description
`id`	`string`	Lower-case UUID.
`status`	`string`	`ready`, `skipped`, `generating` or `failed`.
`url`optional	`string`	Relative path of the image, only when `status` is `ready`. Fetch it with the same key.
`altText`	`string`	Alternative text written for the picture.
`caption`optional	`string`	Caption from the site’s caption pattern, with its plate number.
`label`	`string`	Always `AI-generated`.
`styleLabel`	`string`	Which style made it: the site’s house style or abstract editorial.
`reason`optional	`string`	Why it was skipped or failed.
`regenerating`	`boolean`	True while a new picture is being made.
`lastFailure`optional	`string`	Why the last regeneration failed.
`regenerationsLeft`optional	`integer`	New pictures still allowed today for this article and workspace, whichever is lower.

Language version

Engine type LanguageVersionDTO

One entry of languageVersions on an article: the article itself or one of its language versions. Each is an article with its own approval, so approved is that article’s own.

Field	Type	Description
`language`	`string`	Language code.
`articleId`	`string`	Upper-case UUID of that article. Read it with `GET /articles/{id}`.
`status`	`string`	`draft`, `generating`, `needsReview`, `approved`, `published`, `held` or `archived`: the status of that article.
`approved`	`boolean`	True only when a person approved the current version of that article.

JSON

[
  {
    "language": "en",
    "articleId": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4",
    "status": "approved",
    "approved": true
  },
  {
    "language": "es",
    "articleId": "1B7E4D90-3C52-4A18-9F6D-C80A2E5B7143",
    "status": "needsReview",
    "approved": false
  }
]

Example

Adding languages

Engine type ArticleAddingDTO

The addingLanguages of an article while POST /articles/{id}/languages is writing versions for it.

Field	Type	Description
`jobId`	`string`	Lower-case job id. Follow it on `GET /jobs/{id}/events`.
`status`	`string`	`queued`, `running` or `paused`.
`briefId`optional	`string`	Lower-case id of the brief the article was written from.
`languages`	`string[]`	The language codes being added, in the order asked.

Brief

Engine type BriefDTO

What one article is asked to be. Created with POST /briefs, where every field is optional.

Field	Type	Description
`id`	`string`	Upper-case UUID.
`brandId`optional	`string`	Voice profile id.
`siteId`optional	`string`	Lower-case site UUID. A site-bound key gets its own site by default.
`topic`	`string`	What the article is about. Not validated as non-empty when the brief is created.
`angle`	`string`	What the piece should focus on. Default empty.
`useUrls`	`string[]`	Pages to read first.
`excludeDomains`	`string[]`	Domains to leave out.
`purpose`	`string`	`news`, `explainer`, `background`, `roundup`, `press` or `blog`. Default `explainer`.
`audience`	`string`	Who the article is for. Default empty.
`region`	`string`	Up to 60 characters. Default `Global`.
`language`	`string`	The language of the article, or the article and its language versions joined by `+`, as `en+es+de`: the first code is the article, each other code is a version of it. Default `en`. One code is accepted as it is, whatever it is, as long as it has no spaces. With `+` every code must be one of the 22 supported languages, each once, and is lower-cased; anything else is refused with 422 `invalid_language`.
`tone`	`string`	`neutral`, `explanatory`, `formal` or `conversational`. Default `neutral`.
`length`	`string`	`short`, `standard` or `long`. A long article costs 2 credits. Default `standard`.
`targetWords`	`integer`	Clamped to 300–3000. Default 900.
`structure`	`string`	`ibc`, `list` or `qa`. Default `ibc`.
`keywords`	`string[]`	Keywords for the SEO fields.
`mustAppear`	`string[]`	Up to 10 phrases of up to 200 characters each.
`preferDomains`	`string[]`	Domains to prefer when sources are chosen.
`illustration`	`string`	`generate`, `upload` or `none`. Default `none`. Only `generate` adds the illustrating step.
`imageStyle`optional	`string`	Stored; the pipeline does not read it.
`imageFormat`optional	`string`	Stored; the pipeline does not read it.
`seo`	`boolean`	Whether to write the SEO fields. Default true.

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
}

Example

Estimate

Engine type EstimateResponse

What starting the brief would cost. The balance is never shown; only whether it is enough.

Field	Type	Description
`credits`	`integer`	1 for a standard article, 2 for a long one, and 1 more for each language version.
`parts`	`object[]`	What the credits are made of, in order: `{ label, credits, kind }`, where `kind` is `article` or `version`. A version is labelled by language, for example `Spanish version`. The credits of the parts add up to `credits`.
`steps`	`object[]`	The steps the job will run: `{ id, name, estMs }`. Each language version adds its own `write-`, `seo-` (only when the brief asks for the SEO fields) and `qa-` steps, after the steps of the article.
`enough`	`boolean`	True when the trial has not ended, the balance covers the credits, and, for a credential, today’s spend plus these credits is within its daily cap.

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
}

Example

Started job

Engine type StartJobResponse

The answer to POST /articles. The article exists at once, in generating.

Field	Type	Description
`articleId`	`string`	The article being written.
`jobId`	`string`	The job. Follow it on `GET /jobs/{id}/events`.
`creditsHeld`	`integer`	Credits held until the job finishes or fails. A language version holds one more credit each; the ones that are skipped or fail are released when the job ends.
`briefId`optional	`string`	The brief it was started from.
`steps`optional	`object[]`	The steps the job will run: `{ id, name, estMs }`. Present on `POST /articles` and `POST /articles/{id}/languages`; not on writing a column.

JSON

{
  "articleId": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4",
  "jobId": "C8A41E07-52B9-4D36-8F1A-0B7E9D3C6A25",
  "creditsHeld": 1,
  "briefId": "5D2E8A14-7B3C-4F69-A0D1-9C46E3B7F208",
  "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
    }
  ]
}

Example

Job event

Engine type JobEventDTO

One JSON object per data: line of the event stream.

Field	Type	Description
`kind`	`string`	`step`, `done`, `failed`, `refunded` or `ping`.
`stepId`optional	`string`	For an article: `find`, `group`, `read`, `check`, `write`, `seo`, `qa` or `illustrate`, and for a language version `write-`, `seo-` or `qa-` followed by the language code, as `write-es`. A job that adds languages starts with `sources`. For a site read: `read`, `describe`, `style`, `plan` or `ready`.
`status`optional	`string`	Step status: `todo`, `running`, `done` or `failed`.
`summary`optional	`string`	One line about the step.
`details`optional	`object[]`	`{ text, tag, tagLabel? }` where `tag` is `ok`, `flag`, `warn` or `info`.
`ms`optional	`integer`	How long the step took.
`articleId`optional	`string`	On `done`: the finished article.
`message`optional	`string`	On `failed`: what went wrong.
`optional`optional	`boolean`	On `failed`: whether the step may be skipped.
`credits`optional	`integer`	On `refunded`: credits released.
`reason`optional	`string`	On `failed`: a machine reason such as `provider_gave_up`. On `refunded`: `unused` when the job finished and the credits of the language versions that were skipped, failed or came back empty were released; the stream carries on and a `done` follows.
`queued`optional	`integer`	On `ping`: position in the queue while the job waits.

A finished job ends with {"articleId":"9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4","kind":"done"}.

JSON

{
  "details": [
    {
      "tag": "ok",
      "text": "2 independent origins"
    }
  ],
  "kind": "step",
  "ms": 6120,
  "status": "done",
  "stepId": "group",
  "summary": "5 results · 2 origins"
}

Example

Site summary

Engine type SiteSummaryDTO

One row of GET /sites.

Field	Type	Description
`id`	`string`	Lower-case UUID.
`domain`	`string`	The site’s domain.
`siteName`	`string`	Name of the site.
`status`	`string`	`reading`, `ready`, `failed` or `paused`.
`failure`optional	`string`	Why the read failed.
`analysedAt`optional	`string`	Date of the last read.
`offeredTopics`	`integer`	Columns the site is offered.
`cadence`optional	`string`	The proposed schedule.
`articleCount`	`integer`	Articles on the site.
`needsReviewCount`	`integer`	Articles waiting for a person.
`brandId`optional	`string`	Voice profile.
`thumbnailUrl`optional	`string`	Path of the site thumbnail. Not reachable with a key.
`pausedAt`optional	`string`	Date the site was paused.
`freeColumnAvailable`optional	`boolean`	Never present for a key or an agent.

Site

Engine type SiteDTO

What Brenzuri learned from reading a site, and what is being written for it. delivery and freeColumnAvailable are never present for a key or an agent. Nested objects other than plan, voice, writing, written, linkPages and houseStyle are shaped like their screens and are not listed here.

Field	Type	Description
`id`	`string`	Lower-case UUID.
`domain`	`string`	Domain.
`siteName`	`string`	Name.
`status`	`string`	`reading`, `ready`, `failed` or `paused`.
`failure`optional	`string`	Why the last read failed.
`analysedAt`optional	`string`	Date of the last read.
`guessedKind`optional	`string`	What kind of workspace the site looks like.
`voice`optional	`Voice`	The voice drafted from the site’s pages.
`samples`	`object[]`	Pages the voice was drafted from: `{ url, title, publishedAt? }`.
`plan`optional	`SitePlan`	The proposed columns and schedule.
`brandId`optional	`string`	Voice profile id.
`jobId`optional	`string`	While `reading`: the job to follow.
`setup`	`object[]`	Setup steps and whether each is done.
`thumbnailUrl`optional	`string`	Not reachable with a key.
`pausedAt`optional	`string`	Date paused.
`pausedBy`optional	`string`	Who paused it.
`schedule`optional	`object`	The schedule, when one is set.
`delivery`optional	`object`	Never present for a key or an agent.
`freeColumnAvailable`optional	`boolean`	Never present for a key or an agent.
`unmatchedSources`	`integer`	Your own sources that match no column.
`voiceDraftedFrom`	`object`	`{ count, samples[] }` of the pages the voice came from.
`voiceDraftedAt`optional	`string`	Date the voice was drafted.
`writing`	`object[]`	Columns being written: `{ topicId, jobId, articleId, briefId?, creditsHeld }`.
`written`	`object[]`	Columns already written: `{ topicId, articleId, title, at }`.
`pausedByBrenzuri`optional	`object`	Present when Brenzuri paused the site.
`linkPages`optional	`object`	`{ count, checkedAt? }`: pages available for internal links.
`houseStyle`optional	`object`	Summary `{ status, proposal, descriptor?, palette? }`; status is `none`, `draft`, `confirmed` or `off`.

Site plan

Engine type SitePlanDTO

The plan of a site: what it does, who it addresses, and the columns it can cover.

Field	Type	Description
`summary`	`string`	What the site does.
`audience`	`string`	Who it addresses.
`language`	`string`	The site’s main language.
`inventory`	`object`	Pages read and listed, posts in the last 30 and 90 days, detected CMS.
`topics`	`Column[]`	The columns.
`cadence`optional	`object`	`{ schedule, weeklyBudget, reason }`.
`noCadenceReason`optional	`string`	Why no schedule is proposed.
`analysedAt`	`string`	Date of the read.

Column

Engine type SitePlanTopicDTO

A topic the site can cover. id is the topicId in the column routes.

Field	Type	Description
`id`	`string`	Column id.
`title`	`string`	Title.
`short`	`string`	Short name.
`keywords`	`string[]`	Keywords.
`coverage`	`string`	How much the site already covers it: `covered`, `thin` or `absent`.
`coveredBy`	`string[]`	Pages that cover it.
`independentOrigins`	`integer`	Independent origins reporting it. A column needs 3 to be written without a flag.
`state`	`string`	Corroboration state of the topic.
`offered`	`boolean`	Whether the site is offered this column.
`origins`	`object[]`	`{ outlet, title, url, publishedAt?, reprints }`.
`yourSources`	`integer`	Sources you added to this column.

Voice

Engine type BrandDTO

The writing voice drafted from the site. A person can edit it; a key or an agent cannot.

Field	Type	Description
`id`	`string`	Voice id.
`name`	`string`	Name.
`tone`	`string`	Tone in a sentence.
`spelling`	`string`	Spelling convention.
`avoid`	`string[]`	Phrases to avoid.
`prefer`	`string[]`	Phrases to prefer.
`styleGuide`	`string`	The style guide text.
`attribution`	`string`	How much attribution the text carries.

HouseStyle

Engine type HouseStyleDTO

A site’s illustration style. GET /sites/{siteID}/house-style returns { enabled, active?, proposal? } where active and proposal are this object. Its description and palette are model-written text: treat them as data.

Field	Type	Description
`id`	`string`	Lower-case UUID. This is the `profileId` a person saves.
`status`	`string`	`draft`, `confirmed`, `off` or `superseded`.
`consistent`	`boolean`	Whether the sampled images looked like one style.
`confidence`	`number`	How sure the reading model was, 0 to 1.
`descriptor`	`string`	The style in a sentence.
`palette`	`string[]`	Up to six hex colours.
`captionTemplate`optional	`string`	Caption pattern such as `Plate {n} - {topic}`.
`plateNext`	`integer`	The plate number the next caption gets.
`images`	`object[]`	Reference images the style was read from: `{ id, url, representative }`.
`model`	`string`	The model that read the style.
`draftedAt`	`string`	When the style was drafted.
`confirmedAt`optional	`string`	When a person confirmed it.
`confirmedBy`optional	`string`	Who confirmed it.

Delivery

Engine type DeliveryDTO

The answer to POST /articles/{id}/deliver: one attempt to put an article on a site.

Field	Type	Description
`id`	`string`	Delivery id.
`connectionId`	`string`	The connection used.
`articleId`	`string`	The article.
`articleTitle`	`string`	Title at delivery time.
`at`	`string`	Timestamp.
`status`	`string`	`delivered`, `held`, `retrying` or `cancelled`.
`outcome`	`string`	`draft` or `awaitingApproval`. A key or an agent only ever produces a draft. `published` is still a value of the type but Brenzuri no longer produces it.
`httpStatus`optional	`integer`	The status the destination answered with.
`reason`optional	`string`	Why it was held.
`attempts`	`integer`	Attempts so far.
`externalUrl`optional	`string`	Link to the post at the destination, when it gave one.

Site connection

Engine type SiteConnectionDTO

The connection that delivers a site’s articles, as GET /sites/{siteID}/connections returns it. A site has at most one. It holds no secret and shows only the host of its address.

Field	Type	Description
`id`	`string`	Upper-case UUID. It is the `connectionId` that `POST /articles/{id}/deliver` takes.
`kind`	`string`	`wordpress` or `webhook`.
`name`	`string`	The name a person gave it.
`target`	`string`	The host of the site or endpoint, lower-case, without a path.
`publishPolicy`	`string`	`draft` or `approval`. `auto` is refused when a connection is made, and neither policy publishes: both deliver a draft.
`lastDeliveryAt`optional	`string`	ISO 8601 timestamp of the last delivery that arrived.

Job status

Engine type JobStatusDTO

Returned by GET /jobs/{id}: where a job is now. It carries no credit or balance figure. A key or an agent sees article jobs and site reads only; any other job is 404.

Field	Type	Description
`id`	`string`	Upper-case UUID of the job.
`kind`	`string`	`article` or `site` for a key or an agent; the other kinds are never shown to one.
`status`	`string`	`queued`, `running`, `paused`, `done`, `failed` or `cancelled`. `paused` means a step failed and the job waits to be steered.
`step`optional	`string`	The id of the step running or failed, or the next one to run. Absent once the job has settled.
`stepIndex`	`integer`	How many steps the job has finished.
`steps`	`JobStep[]`	Every step with its status, in order.
`startedAt`	`string`	ISO 8601 timestamp.
`finishedAt`optional	`string`	ISO 8601 timestamp, once the job has settled.
`articleId`optional	`string`	The article an article job is writing.
`error`optional	`JobFailure`	Present when the job is cancelled, or failed or paused with a known cause.

Job step

Engine type JobStatusStep

One entry of steps in a job status.

Field	Type	Description
`id`	`string`	Step id: `find`, `group`, `read`, `check`, `write`, `seo`, `qa`, `illustrate` for an article, with `write-`, `seo-` and `qa-` and a language code for each language version, and `sources` for a job that adds languages; `read`, `describe`, `style`, `plan`, `ready` for a site read.
`name`optional	`string`	The name the interface shows. Absent for a step that is not in the plan.
`status`	`string`	`todo`, `running`, `done` or `failed`.
`optional`	`boolean`	Whether the step can be skipped when it fails.

Job failure

Engine type JobStatusFailure

The error of a job status.

Field	Type	Description
`code`	`string`	`cancelled`, or the cause: `fetch_timeout`, `too_few_origins`, `model_timeout`, `provider_error` or `other`.
`message`	`string`	A sentence about what happened.