API and webhooks
Integration token
A token is a key another service uses to call the onlybrain REST API. It belongs to one member and one brain.
- One brain. The token works only for the brain it was created in. Nobody opens another brain with it.
- Permissions. Read (files, history, search, meetings) and Propose changes (proposed file changes and new notes). Choose one or both.
- At most the role's rights. A token never has more rights than the role of the member who created it, and it follows that role continuously: a change of the role applies to the token right away. What the role does not see, the token cannot read or propose.
- Proposals wait for approval. Changes and notes from an integration do not go straight into the brain. They wait on the Changes tab like any other proposal, labelled "from an integration".
- Validity. 30, 90 (default), 180 or 365 days, no longer. After that the token stops working and a new one is needed.
- Shown only once. The full token is visible only right after it is created. The list keeps only its beginning, e.g.
obi_AbC12345…. - Leaving the brain. When a member leaves the brain or the brain is handed over to another owner, onlybrain revokes all their tokens for this brain for good. They do not come back even if the member is added again.
- Revoke any time. Members revoke their own tokens. Brain managers see every member's tokens, and Revoke all tokens takes access away from all services at once, for example on a suspected leak.
Create a token
- In the brain, open the Settings tab and the Integrations section.
- Click Create token and fill in a name that tells the token apart later (e.g.
n8n: new offers). - Tick Read, Propose changes or both, and choose how long it is Valid for.
- Click Create token, copy the token and store it in the service that will call the brain. In n8n, for example, as a Header Auth credential with the
Authorizationheader and the valueBearer obi_....
After clicking Done, the token cannot be shown again. If it gets lost, revoke the old one and create a new one.
How to call the API
Every request carries the token in the Authorization: Bearer obi_... header. Addresses start with https://api.onlybrain.ai/v1/brains/ORG/BRAIN/, where ORG/BRAIN is the brain's address from its link in the app (for app.onlybrain.ai/acme/knowledge it is acme/knowledge).
Read a file (the response holds its content content and its version sha):
curl -H "Authorization: Bearer obi_..." \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/file?path=clients/acme.md"Search the files (the response is { query, matches: [{ path, line, text }] }):
curl -H "Authorization: Bearer obi_..." \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/search?q=offer"Propose changes (at most 50 files in one proposal). When editing an existing file, send its sha from the read response in base: if the file changed in the meantime, the proposal notices. A new file has "new": true, a deletion "delete": true.
curl -X POST \
-H "Authorization: Bearer obi_..." \
-H "Content-Type: application/json" \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/proposals" \
-d '{
"reason": "New inquiry from the web form",
"changes": [
{
"path": "clients/acme.md",
"content": "# Acme\n\nInquiry: online shop",
"base": "<sha from reading the file>"
},
{
"path": "clients/new.md",
"new": true,
"content": "# New client\n"
}
]
}'The 201 response holds the created proposal review and an overview changed, created, deleted, unchanged with a message.
Add a note (also as a proposal for approval, folder is an optional folder):
curl -X POST \
-H "Authorization: Bearer obi_..." \
-H "Content-Type: application/json" \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/notes" \
-d '{
"title": "Call with Acme",
"content": "Demo agreed for Tuesday.",
"folder": "clients/acme"
}'The 201 response holds the created proposal review, the new note's path path and a message.
What a token may call
All paths are under /v1/brains/ORG/BRAIN, and only for the token's brain.
| Permission | Request | What it returns or does |
|---|---|---|
| Read | GET /tree | The tree of files the role sees |
| Read | GET /file?path=… | A text file's content (content) and its version (sha) |
| Read | GET /file/raw?path=… | The file as it is (PDF, image, Office) |
| Read | GET /files/meta | When files were created, when they last changed and who changed them |
| Read | GET /files/activity | What was created, changed or deleted in a period |
| Read | GET /history | The change history |
| Read | GET /search?q=… | Matching lines: path, line, text |
| Read | GET /meetings, GET /meetings/:id | Meetings and a single meeting |
| Propose changes | POST /proposals | A proposal of changes to at most 50 files, waits for approval |
| Propose changes | POST /notes | A new note as a proposal, waits for approval |
For anything else the token gets a 403, for another brain a 404, and a revoked or expired token gets a 401.
API description (OpenAPI)
All these requests and the webhook bodies are described in a machine-readable OpenAPI document: parameters and their limits, example requests, the shape of the answers and the error codes of each request.
- OpenAPI: https://api.onlybrain.ai/v1/openapi/integrations.json
- Swagger UI: https://api.onlybrain.ai/docs/integrations, where requests can be tried out right away with a token (the Authorize button)
The OpenAPI address can be loaded into Postman, Insomnia or a client generator. The webhook bodies are in the x-webhooks section of the description and among the schemas at the bottom of Swagger UI (e.g. BrainChangedEventDto).
Limits and errors
- At most 60 requests per minute per token.
- At most 30 proposals and notes per hour per token.
- Over the limit, the response is a
429with aRetry-Afterheader: the number of seconds after which the request can be retried.
An error always has the same shape: code is a stable code for programs and message a sentence for people.
{ "error": { "code": "FORBIDDEN", "message": "..." } }Messages are in Czech by default. With the Accept-Language: en header, they come in English.
Webhooks
A webhook is the other direction: onlybrain itself sends another service a message when something happens in the brain (a new change, a proposal waiting for approval, a decision on a proposal, a finished meeting, a member added or removed). Brain managers set webhooks up in Settings, in the Webhooks section. A message holds only data about the event, never file content. When the service needs the content, it reads it with an integration token.
Every message carries these headers:
X-Onlybrain-Signature:sha256=followed by the hex HMAC-SHA256 of the message body, signed with the webhook's secret (whsec_…, shown only once when the webhook is added),X-Onlybrain-Event: the kind of event, e.g.brain.changed,X-Onlybrain-Delivery: the delivery number, which stays the same on another attempt at the same delivery,X-Onlybrain-Timestamp: the time of this attempt in seconds (Unix time).
The body is always { id, event, createdAt, brain, data }. The id field stays the same on retries and after Send again, so a message that already arrived can be recognised by it.
Verifying the signature in Node.js. The signature covers the body exactly as it arrived, not re-serialized JSON:
import { createHmac, timingSafeEqual } from 'node:crypto'
// rawBody: the request body exactly as it arrived (Buffer or string), not re-serialized JSON
const verify = (rawBody, header, secret) => {
const expected = 'sha256=' + createHmac('sha256', secret).update(rawBody).digest('hex')
return typeof header === 'string' && header.length === expected.length && timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}Drop a message with an invalid signature. The events and their content are described in detail in the OpenAPI description (the x-webhooks section) and in the API documentation.
Safely
- Give a token only what the service really needs. For overviews and reports, Read is enough.
- Store a token only in a password manager or in the service's credentials, never in the brain, in code in a repository or in a shared document.
- Create a separate token for each service. On a problem, only that one needs revoking.
- Every now and then, check in Settings → Integrations when each token was last used, and revoke the unused ones.