Write

Upload a file, capture a link, and edit one of your own notes through the API, with idempotency and what each call returns.

Report a problem with this page

These operations need the write scope, and a viewer's token cannot write. Each is recorded in the audit log with the token's id, and the items they create are owned by the token's owner.

Upload a file#

bash

curl -s -H "Authorization: Bearer $TOKEN" -H "Idempotency-Key: $(uuidgen)" \
  -F file=@report.pdf "$BRENO/documents/upload"

POST /documents/upload takes multipart/form-data with a file, an optional visibility (workspace, the default, or private) and an optional source_type (upload, note, voice or photo), and returns 201 once ingestion is accepted. The file is then read and indexed in the background; poll the item's status. The limits and supported types are in Supported files and limits. Uploads cost one coin per page started.

Capture a link#

bash

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article","visibility":"workspace"}' "$BRENO/documents/capture"

Field	Meaning
`url`	Required. The link to save.
`depth`	`concise`, `detailed` (default) or `full-notes`.
`tags`	Tags to attach.
`visibility`	`workspace` (default) or `private`: only the capturer can read it.

It returns 202 with the item's document_id, a job_id, a status, and duplicate. duplicate: true means this link was already captured, and document_id is the existing item.

A link whose content type Breno cannot read returns 422 SOURCE_UNSUPPORTED, and nothing is saved.

Edit a note#

bash

curl -s -X PATCH -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"plain_text":"Updated meeting notes…"}' "$BRENO/documents/$ID/content"

PATCH /documents/{id}/content saves the note's text and queues a full re-index. When the text changed, the previous text is kept as a version. With a token you can edit only notes your account created; any other note returns 403 TOKEN_OWN_NOTES_ONLY. The body takes plain_text (required) and optionally content_json, the block-editor JSON. Read a note's content first with GET /documents/{id}/content, which returns the same two fields.

Idempotency#

Send an Idempotency-Key header on upload and capture. A repeated request with the same key replays the stored response, so a retry after a timeout cannot create two items.

Duplicates#

Identical content already in the workspace returns the existing item rather than a new one.