API overview
The Breno REST API at a glance: base path, the response envelope, the seventeen operations a personal token can call, idempotency, and where the contract lives.
The public API lets your own scripts and tools take knowledge out of Breno and put it back in, with the same access rules as the app. Anything it does, a person could do in the product, as the token's owner and no more.
Base#
All paths are under /api/v1 on your Breno host.
https://<your-breno-host>/api/v1Requests and responses are JSON, except file uploads (multipart/form-data), export archives (application/zip) and the streamed answer (text/event-stream).
The response envelope#
A successful JSON response wraps its payload:
{ "success": true, "data": { } }An error uses a single envelope. See Errors.
{ "success": false, "error": { "code": "INSUFFICIENT_SCOPE", "message": "…", "details": { } } }The seventeen operations#
A personal token can call exactly these. Every other endpoint refuses tokens with 403 SESSION_REQUIRED.
| Scope | Operation | Route |
|---|---|---|
read | List items | GET /documents |
read | List items as cards | GET /documents/cards |
read | Get an item | GET /documents/{id} |
read | Full extracted text | GET /documents/{id}/text |
read | A note's content | GET /documents/{id}/content |
read | Search passages | POST /search/query |
read | List native connectors | GET /connectors |
read | List connected sources | GET /integrations/connections |
ask | Ask, with citations | POST /search/ask |
ask | Ask, streamed | GET /search/ask/stream |
export | JSON bundle | POST /knowledge/export |
export | ZIP archive (up to 500 items) | POST /knowledge/export/zip |
export | Start an asynchronous export | POST /knowledge/exports |
export | Download a finished export | GET /knowledge/exports/{id}/download |
write | Upload a file | POST /documents/upload |
write | Capture a link | POST /documents/capture |
write | Edit one of your own notes | PATCH /documents/{id}/content |
Idempotency#
POST /documents/upload and POST /documents/capture accept an Idempotency-Key header. A repeated request with the same key replays the stored response instead of doing the work twice, so it is safe to retry after a network failure.
The contract#
The full contract is the OpenAPI document, served at /api/v1/openapi.json. A test fails if the token allowlist, the router and the spec's public operations disagree, or if a public schema's fields differ from what the server writes. See Authentication to get started.