Endpoints: jobs

Read where a job is now: its status, the step it is on and every step with its status. This is the route to poll when you cannot hold an event stream open.

Path

Response

200The Job status. No credit or balance figure is in it.

{
  "id": "C8A41E07-52B9-4D36-8F1A-0B7E9D3C6A25",
  "kind": "article",
  "status": "running",
  "step": "check",
  "stepIndex": 3,
  "steps": [
    {
      "id": "find",
      "name": "Searching your domains",
      "status": "done",
      "optional": false
    },
    {
      "id": "group",
      "name": "Grouping by origin",
      "status": "done",
      "optional": false
    },
    {
      "id": "read",
      "name": "Reading one page per origin",
      "status": "done",
      "optional": false
    },
    {
      "id": "check",
      "name": "Checking claims across origins",
      "status": "running",
      "optional": false
    },
    {
      "id": "write",
      "name": "Writing",
      "status": "todo",
      "optional": false
    },
    {
      "id": "seo",
      "name": "Writing the SEO fields",
      "status": "todo",
      "optional": true
    },
    {
      "id": "qa",
      "name": "Reading the finished text back",
      "status": "todo",
      "optional": false
    }
  ],
  "startedAt": "2026-10-06T12:00:03Z",
  "articleId": "9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4"
}

Errors

• status is queued, running, paused, done, failed or cancelled. A job is finished when it is done, failed or cancelled; paused means a step failed and the job waits to be steered.
• step is absent once the job has finished. error carries the cause when a job failed or was cancelled.
• Polling every 3 to 5 seconds is enough: a job takes minutes. The route counts against the 60 requests a minute of the credential.

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

Follow a job as a server-sent event stream. It replays what has happened and then streams new events. The stream closes after done, or after a refunded that ends a failed or cancelled job.

Path

Response

200 text/event-streamFrames of id: <sequence> and data: <Job event JSON>. A comment line : brenzuri job <id> opens the stream.

: brenzuri job C8A41E07-52B9-4D36-8F1A-0B7E9D3C6A25

id: 1
data: {"details":[{"tag":"ok","text":"3 domains searched"}],"kind":"step","ms":14210,"status":"done","stepId":"find","summary":"8 results"}

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

: ping is sent as  data: {"kind":"ping"}  every 20 s, and every 5 s with "queued" while waiting

id: 9
data: {"articleId":"9F3B1C2A-6D4E-4B7A-8C15-2E0A7D91B3F4","kind":"done"}

Errors

• Send Last-Event-ID with the last sequence you saw to resume without replaying.
• An article job opens with one todo event for each step of its plan, language version steps included, so a client can draw the whole list before the first step runs.
• A refunded event with reason: "unused" comes just before done. It carries the credits of the language versions that were skipped, failed or came back empty, and does not close the stream. A refunded without that reason means the job failed or was cancelled.
• ping events keep the connection alive: every 20 seconds, and every 5 seconds with queued (the position) while the job waits. They carry no sequence number.
• A failed step does not close the stream. The job pauses and the stream stays open until the step is steered, or until the job is failed and refunded.
• For a snapshot instead of a stream, read the job status, or use a webhook.

Run the failed step again. A step that has failed more than 3 times, or failed terminally, settles the job as failed and releases the credits.

Path

Response

204No body.

Errors

curl -X POST "$BRENZURI_URL/api/v1/jobs/$JOB_ID/steps/$STEP_ID/retry" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Skip a failed optional step (seo, illustrate, or a language version step such as write-es) and let the job carry on. Steps that affect what the article claims about its sources cannot be skipped.

Path

Response

204No body.

Errors

• Skipping the write- or qa- step of a language leaves that language out: its other steps are skipped with it, no article is made for it, and its credit is released when the job finishes. Skipping its seo- step keeps the version and leaves its SEO fields out.

curl -X POST "$BRENZURI_URL/api/v1/jobs/$JOB_ID/steps/$STEP_ID/skip" \
  -H "Authorization: Bearer $BRENZURI_KEY"

Cancel a job. The credits it held are released and job.failed is raised with failure: "cancelled".

Path

Response

204No body.

Errors

curl -X POST "$BRENZURI_URL/api/v1/jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $BRENZURI_KEY"