> ## Documentation Index
> Fetch the complete documentation index at: https://docs.verelyn.com/llms.txt
> Use this file to discover all available pages before exploring further.

# REST reference

> Released external newsroom routes.

# REST reference

Base URL: `https://verelyn.com/api/external/v1`. Send the bearer token obtained by browser OAuth. Never paste it into documentation, a support message, or a chat. These routes are deployed contracts; authorized live use is access dependent.

| Method and route                  | Permission                         | Input                               | Effect                                          |
| --------------------------------- | ---------------------------------- | ----------------------------------- | ----------------------------------------------- |
| `GET /newsroom`                   | `newsroom_read` or `mandate_write` | none                                | Reads stored readiness and latest sent edition. |
| `GET /briefing?edition_number=12` | `newsroom_read` or `mandate_write` | optional positive edition number    | Reads a stored sent edition.                    |
| `GET /mandate`                    | `mandate_write`                    | none                                | Reads the mandate.                              |
| `POST /mandate`                   | `mandate_write`                    | correction body                     | Records a confirmed correction when applied.    |
| `GET /updates?cursor=...`         | `newsroom_read` or `mandate_write` | optional opaque cursor              | Reads sent updates and records retrieval.       |
| `GET /monitors`                   | `mandate_write`                    | none                                | Lists followed situations.                      |
| `POST /monitors`                  | `mandate_write`                    | exactly one `item_id` or `alert_id` | Starts a monitor.                               |
| `POST /monitors/{id}`             | `mandate_write`                    | `state`                             | Pauses, resumes, or irreversibly stops it.      |
| `POST /onboarding`                | `onboarding_write`                 | `command_id`                        | Starts an onboarding draft.                     |
| `GET /onboarding?draft_id=...`    | `onboarding_write`                 | opaque draft ID                     | Reads a draft.                                  |
| `POST /onboarding/answers`        | `onboarding_write`                 | answer command                      | Records an onboarding answer.                   |

## Exact write bodies

UUID fields are `command_id`, `draft_id`, `target_answer_id`, `item_id`, `alert_id`, and a monitor path `{id}`. `question_id` is a non-empty string of at most 160 characters; use the value returned by the service unchanged.

`POST /mandate`:

```json theme={null}
{"command_id":"00000000-0000-4000-8000-000000000101","expected_revision":4,"statement":"Follow Example Robotics less closely.","provenance":"reader_words"}
```

`expected_revision` is a non-negative integer; `statement` is 1–2,000 characters; `provenance` is `reader_words` or `assistant_suggestion`. `GET /mandate` does not expose the revision, so use the web editor unless a supported product flow supplied it.

`POST /monitors` takes exactly one field, never both:

```json theme={null}
{"alert_id":"00000000-0000-4000-8000-000000000201"}
```

`POST /monitors/{id}`:

```json theme={null}
{"state":"paused"}
```

Monitor `state` is `active`, `paused`, or `stopped`. `GET /updates` supplies alert IDs as `items[].id`; `GET /briefing` does not expose edition item IDs, so use the web edition for that starting path.

`POST /onboarding`:

```json theme={null}
{"command_id":"00000000-0000-4000-8000-000000000301"}
```

`POST /onboarding/answers` always requires UUID `draft_id`, UUID `command_id`, non-negative `expected_revision`, `action`, and `provenance` (`reader_answer` or `assistant_suggestion`). `action` is `answer`, `correct`, `skip`, or `retry`. `answer` requires `question_id`, `question_text`, and non-empty `answer`; `correct` also requires UUID `target_answer_id`; `skip` requires the two question fields; `retry` needs no extra action field. Optional `timezone` is an IANA time-zone name.

An accepted answer can return:

```json theme={null}
{"draft_id":"00000000-0000-4000-8000-000000000302","revision":5,"status":"collecting","answers":[],"accepted":{"command_id":"00000000-0000-4000-8000-000000000303","answer_id":"00000000-0000-4000-8000-000000000304"},"alerts_notice":null}
```

## Response envelopes

REST success returns the documented object directly as JSON. A successful mandate correction is shaped like:

```json theme={null}
{"revision":5,"outcome":"applied","acknowledgement":"Noted.","question":null,"interests":[{"label":"Example Robotics","covered":true}]}
```

REST failures use `{"error":{"code":"invalid_cursor","message":"That cursor is not one this newsroom issued."}}`. An `internal_error` may also contain `correlation_id`, which is safe to quote to support. Authorization failures are generic and do not disclose whether another account owns an identifier.