Developers

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.

Get a token

  1. In Breno, open Settings, then Connect AI.
  2. Create a token, give it a name and choose its scopes and expiry.
  3. Copy it. It starts with sirmx_mcp_ and is shown only once.

The same token works on the MCP endpoint and on the REST API. Send it as:

http
Authorization: Bearer sirmx_mcp_…

A token belongs to you in one workspace. It sees exactly what you can see: spaces you belong to, sensitivity labels you are cleared for, and your own private items. It stops working at once when you revoke it, it expires, you leave the workspace, your account is erased, or the workspace is deleted.

Tokens issued to an OAuth connector (Claude.ai, ChatGPT) work only on the MCP endpoint; the REST API answers 401 TOKEN_AUDIENCE_MISMATCH.

Scopes and operations

ScopeOperationRoute
readList documents (filters, paging)GET /api/v1/documents
readList documents as cards, with summariesGET /api/v1/documents/cards
readGet a documentGET /api/v1/documents/{id}
readFull extracted textGET /api/v1/documents/{id}/text
readNote contentGET /api/v1/documents/{id}/content
readSearch passages (no generation)POST /api/v1/search/query
readList native connectorsGET /api/v1/connectors
readList connected sources with sync statusGET /api/v1/integrations/connections
askGrounded answer with citationsPOST /api/v1/search/ask
askStreamed answer (server-sent events)GET /api/v1/search/ask/stream
exportJSON bundlePOST /api/v1/knowledge/export
exportZIP of Markdown filesPOST /api/v1/knowledge/export/zip
exportStart an asynchronous exportPOST /api/v1/knowledge/exports
exportDownload a finished export archiveGET /api/v1/knowledge/exports/{id}/download
writeUpload a filePOST /api/v1/documents/upload
writeCapture a linkPOST /api/v1/documents/capture
writeEdit one of your own notesPATCH /api/v1/documents/{id}/content

Every other endpoint (deleting, sharing, members, settings, token management, connecting sources, and so on) refuses tokens with 403 SESSION_REQUIRED, so a leaked token can never administer your workspace. Viewers cannot write with a token either.

GET /documents filters: source_type, status, space_id, tag, owner (a user id or me), q (title contains), updated_since (RFC 3339), plus limit (max 200) and offset.

Examples

curl
export BRENO=https://<your-breno-host>/api/v1
export TOKEN=sirmx_mcp_…

# List your notes changed this week
curl -s -H "Authorization: Bearer $TOKEN" \
  "$BRENO/documents?source_type=note&updated_since=2026-10-01T00:00:00Z&limit=50"

# Search without generating an answer
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"query":"data retention policy"}' "$BRENO/search/query"

# Ask (scope ask)
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"question":"What did we decide about the Q3 launch?"}' "$BRENO/search/ask"

# Export everything you can read as Markdown (scope export)
curl -s -X POST -H "Authorization: Bearer $TOKEN" -o breno-export.zip "$BRENO/knowledge/export/zip"

# Add knowledge (scope write)
curl -s -H "Authorization: Bearer $TOKEN" -F file=@report.pdf "$BRENO/documents/upload"
curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"url":"https://example.com/article"}' "$BRENO/documents/capture"

SDKs

Both SDKs are in the repository, cover the public API, and are tested against the spec’s schemas: packages/sdk-ts and packages/sdk-go. The CLI (apps/cli) can bridge the MCP endpoint over stdio with a scoped token.

TypeScript
import { BrenoClient, RateLimitError } from '@brainers/sdk-ts';

const breno = new BrenoClient({ baseUrl: 'https://<your-breno-host>', token: process.env.BRENO_TOKEN! });

for await (const doc of breno.iterateDocuments({ owner: 'me' })) console.log(doc.title);
const answer = await breno.ask('What is our refund policy?');
answer.evidence.forEach((c) => console.log(c.source?.url ?? c.document_id));
await breno.captureNote('Standup 8 Oct', '- shipped the REST API');
Go
c := client.NewClient(client.Config{BaseURL: "https://<your-breno-host>", Token: os.Getenv("BRENO_TOKEN")})
it := c.Documents(client.ListOptions{SourceType: "note"})
for it.Next(ctx) {
	fmt.Println(it.Document().Title)
}
bundle, err := c.Export(ctx)

Rate limits

  • 120 requests per minute per token, and 300 per minute per IP address for token traffic.
  • The workspace’s normal per-user limits also apply.
  • Over the limit you get 429 RATE_LIMIT_EXCEEDED with a Retry-After header, in seconds.

Errors

Every error uses one envelope:

json
{ "success": false, "error": { "code": "INSUFFICIENT_SCOPE", "message": "This token lacks the 'export' scope", "details": { "required_scope": "export" } } }
StatusCodeMeaning
400INVALID_FILTER, INVALID_BODY, …Bad request
401INVALID_TOKENUnknown, expired or revoked token, or you lost access to the workspace
401TOKEN_AUDIENCE_MISMATCHAn OAuth connector token used on the REST API
403INSUFFICIENT_SCOPEThe token lacks the scope (details.required_scope)
403SESSION_REQUIREDThe endpoint is not part of the public API
403TOKEN_OWN_NOTES_ONLYA token can edit only notes its owner created
403READ_ONLY_ROLEViewers cannot make changes
404NOT_FOUNDNo such item, or one you cannot read
422SOURCE_UNSUPPORTEDA link Breno cannot read; nothing was saved
429RATE_LIMIT_EXCEEDEDSlow down; retry after the Retry-After header

Keeping the contract honest

  • A test fails if the token allowlist, the router and the spec’s public operations disagree, in either direction and including scopes, or if a public schema’s fields differ from what the server writes.
  • Both SDKs test their models against the spec’s schemas.

Back to the home page