Reference

Endpoints: sites and columns

A key sees only its own site when it is bound to one.

On this page

A site is read once and then offers columns: topics it can cover. A key bound to a site sees only that site. Reading a site again, checking a topic and adding a column source share their allowances with people using the interface.

GET`/api/v1/sites`

Scoperead
Credits free

List the sites this credential can see. A site-bound credential sees one.

Response

200An array of Site summary. freeColumnAvailable is never present for a key or an agent.

JSON

[
  {
    "id": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
    "domain": "kolibri.example",
    "siteName": "Kolibri Courier",
    "status": "ready",
    "analysedAt": "2026-09-28",
    "offeredTopics": 7,
    "cadence": "Tuesday and Friday",
    "articleCount": 23,
    "needsReviewCount": 2,
    "thumbnailUrl": "/api/v1/sites/3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0/thumbnail?v=1790000000"
  }
]

thumbnailUrl points at a route a key cannot call.

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

Example request

GET`/api/v1/sites/{siteID}`

Scoperead
Credits free

Read one site: its voice, plan of columns, what is being written, and a summary of its house style. delivery and freeColumnAvailable are never present for a key or an agent.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).

Response

200The Site.

JSON

{
  "id": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "domain": "kolibri.example",
  "siteName": "Kolibri Courier",
  "status": "ready",
  "analysedAt": "2026-09-28",
  "voice": {
    "id": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0-voice",
    "name": "Kolibri Courier",
    "tone": "Plain, local, specific",
    "spelling": "british",
    "avoid": [
      "game-changing"
    ],
    "prefer": [
      "name the road or the pier"
    ],
    "styleGuide": "Short paragraphs. Numbers before adjectives.",
    "attribution": "light"
  },
  "samples": [],
  "plan": {
    "summary": "A local paper for the northern coast.",
    "audience": "Residents and commuters",
    "language": "en",
    "inventory": {
      "pagesRead": 12,
      "pagesListed": 140,
      "hasBlog": true,
      "postsLast90Days": 31,
      "postsLast30Days": 11,
      "titleOnly": false
    },
    "topics": [
      {
        "id": "ferry-timetables",
        "title": "Ferry timetables on the northern coast",
        "short": "Ferry timetables",
        "keywords": [
          "ferry",
          "timetable",
          "northern route"
        ],
        "coverage": "absent",
        "coveredBy": [],
        "independentOrigins": 4,
        "state": "ready",
        "offered": true,
        "origins": [
          {
            "outlet": "harbour-authority.example",
            "title": "Northern route: one timetable from 3 November",
            "url": "https://harbour-authority.example/news/northern-route-timetable",
            "publishedAt": "2026-10-02",
            "reprints": 0
          }
        ],
        "yourSources": 0
      }
    ],
    "cadence": {
      "schedule": "Tuesday and Friday",
      "weeklyBudget": 2,
      "reason": "The site publishes about 11 posts a month."
    },
    "analysedAt": "2026-09-28"
  },
  "unmatchedSources": 0,
  "voiceDraftedFrom": {
    "count": 0,
    "samples": []
  },
  "writing": [],
  "written": [],
  "houseStyle": {
    "status": "confirmed",
    "proposal": false,
    "descriptor": "Flat gouache shapes in muted harbour colours, generous empty sky.",
    "palette": [
      "#1F3A5F",
      "#C9B28F",
      "#6E8B74"
    ]
  }
}

Errors

Status	Code	When
404	not_found	No such site, or not one this credential can see.

The example is abridged: samples, setup and the nested objects are shortened. The fields are in Objects.

curl "$BRENZURI_URL/api/v1/sites/$SITE_ID" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Example request

POST`/api/v1/sites/{siteID}/analyze`

Scopeedit
Credits free
Role edit

Read the site again. It is a job: follow jobId on the event stream, or wait for the site.read webhook. A re-read proposes a new house style beside the confirmed one and never overwrites it.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).

Response

200{ siteId, jobId, steps }, where steps is the list of steps the read will run.

JSON

{
  "siteId": "3b6f0c52-6a41-4d0e-9a53-71c8f2d5a1e0",
  "jobId": "C8A41E07-52B9-4D36-8F1A-0B7E9D3C6A25",
  "steps": [
    {
      "id": "read",
      "name": "Read your site",
      "estMs": 2000
    },
    {
      "id": "describe",
      "name": "Described the site",
      "estMs": 6000
    },
    {
      "id": "style",
      "name": "Reading the illustration style",
      "estMs": 8000
    },
    {
      "id": "plan",
      "name": "Checking sources",
      "estMs": 11000
    },
    {
      "id": "ready",
      "name": "Plan ready",
      "estMs": 400
    }
  ]
}

Errors

Status	Code	When
409	site_reading	A read is already running.
429	rate_limited	More than 5 reads for this workspace in 24 hours.

The style step reads the illustration style and is optional: if it fails the read still finishes.

curl -X POST "$BRENZURI_URL/api/v1/sites/$SITE_ID/analyze" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Example request

POST`/api/v1/sites/{siteID}/topics/check`

Scopebrief
Credits free

Count the independent origins for a topic before committing to a brief. It runs a live web search, so it is limited.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).

Body

Name	Type	Description
`topic`required	`string`	The topic in words.

Response

200independentOrigins, state (ready from 3 origins, thin from 1, none), whether the site already covers it, which pages cover it, whether it is in the library, and credits the article would cost.

JSON

{
  "independentOrigins": 4,
  "state": "ready",
  "coveredOnSite": false,
  "coveredBy": [],
  "inLibrary": false,
  "credits": 1
}

Errors

Status	Code	When
409	site_not_ready	The site is not ready.
429	rate_limited	60 checks a day for the workspace, or 2 running at once.

curl -X POST "$BRENZURI_URL/api/v1/sites/$SITE_ID/topics/check" \
  -H "Authorization: Bearer $BRENZURI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "Ferry timetables on the northern coast"
  }'

Example request

GET`/api/v1/sites/{siteID}/topics/{topicId}`

Scoperead
Credits free

Read one column: the topic, its origins, and the sources you have added.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).
`topicId`	`string`	The column id: the `id` of an entry in the site plan’s `topics`.

Response

200{ topic, origins, yourSources, workspaceSources }. topic is a Column.

JSON

{
  "topic": {
    "id": "ferry-timetables",
    "title": "Ferry timetables on the northern coast",
    "short": "Ferry timetables",
    "keywords": [
      "ferry",
      "timetable",
      "northern route"
    ],
    "coverage": "absent",
    "coveredBy": [],
    "independentOrigins": 4,
    "state": "ready",
    "offered": true,
    "origins": [
      {
        "outlet": "harbour-authority.example",
        "title": "Northern route: one timetable from 3 November",
        "url": "https://harbour-authority.example/news/northern-route-timetable",
        "publishedAt": "2026-10-02",
        "reprints": 0
      }
    ],
    "yourSources": 0
  },
  "origins": [
    {
      "outlet": "harbour-authority.example",
      "title": "Northern route: one timetable from 3 November",
      "url": "https://harbour-authority.example/news/northern-route-timetable",
      "publishedAt": "2026-10-02",
      "reprints": 0
    }
  ],
  "yourSources": [],
  "workspaceSources": []
}

Errors

Status	Code	When
404	not_found	No such site or column.

curl "$BRENZURI_URL/api/v1/sites/$SITE_ID/topics/$TOPIC_ID" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Example request

POST`/api/v1/sites/{siteID}/topics/{topicId}/write`

Scopegenerate
Credits 1, or 2 for a long brief; held, captured when done
Role edit

Write a column. The brief is built from the plan, so no brief is needed. A key or an agent never gets the free first column.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).
`topicId`	`string`	The column id: the `id` of an entry in the site plan’s `topics`.

Body

Name	Type	Description
`flagged`	`boolean`	Write a column that has fewer than 3 independent origins. Its single-source claims are marked.

Response

200The Started job. If the column is already being written the running job is returned.

JSON

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

Errors

Status	Code	When
409	column_not_ready	Fewer than 3 independent origins and `flagged` was not sent.
409	site_not_ready	The site is paused or not ready.
402	insufficient_credits	The workspace cannot cover it.
429	budget_exhausted	The credential’s daily cap.

curl -X POST "$BRENZURI_URL/api/v1/sites/$SITE_ID/topics/$TOPIC_ID/write" \
  -H "Authorization: Bearer $BRENZURI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "flagged": false
  }'

Example request

POST`/api/v1/sites/{siteID}/topics/{topicId}/sources`

Scopeedit
Credits free
Role edit

Add a source to a column: a page to read, a note you wrote, or a copy of another source. Send exactly one of url, note, copyOf. A column holds at most 10 of your sources.

Path

Name	Type	Description
`siteID`	`string`	The site id (lower-case UUID).
`topicId`	`string`	The column id: the `id` of an entry in the site plan’s `topics`.

Body

Name	Type	Description
`url`	`string`	A page. https only; read through the hardened fetcher.
`note`	`string`	Text of your own.
`copyOf`	`string`	The id of another source to copy.

Response

200The column, as GET /sites/{siteID}/topics/{topicId} returns it.

Errors

Status	Code	When
400	validation	None, or more than one, of `url`, `note` and `copyOf`.
415	unsupported_pdf	A PDF. Paste the page or a note instead.
422	unreadable_source	The page could not be read or has no text.
409	too_many_sources	The column already holds 10.
409	source_exists	That source is already there.
400	unsafe_url	The address points at a private network.

curl -X POST "$BRENZURI_URL/api/v1/sites/$SITE_ID/topics/$TOPIC_ID/sources" \
  -H "Authorization: Bearer $BRENZURI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://coast-gazette.example/transport/ferries-share-timetable"
  }'

Example request