API a webhooky
Token pro integraci
Token je klíč, se kterým jiná služba volá REST API onlybrainu. Patří jednomu členovi a jednomu brainu.
- Jeden brain. Token platí jen pro brain, ve kterém vznikl. Jiný brain s ním neotevře nikdo.
- Oprávnění. Číst (soubory, historie, hledání, schůzky) a Navrhovat změny (návrhy změn souborů a nové poznámky). Jde zvolit jedno nebo obojí.
- Nejvýš práva role. Token nemá nikdy víc práv než role člena, který ho vytvořil, a řídí se jí průběžně: změna role pro token platí hned. Co role nevidí, token nepřečte ani nenavrhne.
- Návrhy čekají na schválení. Změny a poznámky z integrace nejdou rovnou do brainu. Čekají na záložce Změny jako každý jiný návrh, s popiskem „z integrace“.
- Platnost. 30, 90 (výchozí), 180 nebo 365 dní, déle ne. Pak token přestane fungovat a je potřeba vytvořit nový.
- Zobrazí se jen jednou. Celý token je vidět jen hned po vytvoření. V seznamu zůstane jen jeho začátek, např.
obi_AbC12345…. - Odchod z brainu. Když člen z brainu odejde nebo je brain předaný jinému vlastníkovi, onlybrain všechny jeho tokeny tohoto brainu zruší natrvalo. Ani po novém přidání člena se nevrátí.
- Zrušit jde kdykoli. Člen ruší své tokeny. Správci brainu vidí tokeny všech členů a tlačítkem Zrušit všechny tokeny vezmou přístup všem službám najednou, třeba při podezření na únik.
Vytvořit token
- V brainu otevřít záložku Nastavení a sekci Integrace.
- Kliknout na Vytvořit token a vyplnit název, podle kterého půjde token později poznat (např.
n8n: nové nabídky). - Zaškrtnout Číst, Navrhovat změny nebo obojí a zvolit platnost.
- Kliknout na Vytvořit token, token zkopírovat a uložit do služby, která bude brain volat. V n8n třeba jako přihlašovací údaj typu Header Auth s hlavičkou
Authorizationa hodnotouBearer obi_....
Po kliknutí na Hotovo token znovu zobrazit nejde. Při ztrátě stačí starý zrušit a vytvořit nový.
Jak volat API
Každý požadavek nese token v hlavičce Authorization: Bearer obi_.... Adresy začínají https://api.onlybrain.ai/v1/brains/ORG/BRAIN/, kde ORG/BRAIN je adresa brainu z jeho odkazu v aplikaci (z app.onlybrain.ai/firma/znalosti je to firma/znalosti).
Přečíst soubor (v odpovědi je jeho obsah content a verze sha):
curl -H "Authorization: Bearer obi_..." \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/file?path=klienti/acme.md"Hledat v souborech (odpověď { query, matches: [{ path, line, text }] }):
curl -H "Authorization: Bearer obi_..." \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/search?q=nabidka"Navrhnout změny (nejvýš 50 souborů v jednom návrhu). U úpravy existujícího souboru poslat v base jeho sha z odpovědi na čtení: když se soubor mezitím změnil, návrh to pozná. Nový soubor má "new": true, smazání "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": "Nová poptávka z webového formuláře",
"changes": [
{
"path": "klienti/acme.md",
"content": "# Acme\n\nPoptávka: e-shop",
"base": "<sha ze čtení souboru>"
},
{
"path": "klienti/novy.md",
"new": true,
"content": "# Nový klient\n"
}
]
}'Odpověď 201 obsahuje vzniklý návrh review a přehled changed, created, deleted, unchanged se zprávou message.
Přidat poznámku (také jako návrh ke schválení, folder je nepovinná složka):
curl -X POST \
-H "Authorization: Bearer obi_..." \
-H "Content-Type: application/json" \
"https://api.onlybrain.ai/v1/brains/ORG/BRAIN/notes" \
-d '{
"title": "Hovor s Acme",
"content": "Domluveno demo na úterý.",
"folder": "klienti/acme"
}'Odpověď 201 obsahuje vzniklý návrh review, cestu nové poznámky path a message.
Co token smí volat
Všechny cesty jsou pod /v1/brains/ORG/BRAIN a jen pro brain tokenu.
| Oprávnění | Požadavek | Co vrátí nebo udělá |
|---|---|---|
| Číst | GET /tree | Strom souborů, které role vidí |
| Číst | GET /file?path=… | Obsah textového souboru (content) a jeho verzi (sha) |
| Číst | GET /file/raw?path=… | Soubor tak, jak je (PDF, obrázek, Office) |
| Číst | GET /files/meta | Kdy soubory vznikly, kdy se naposledy změnily a kdo je měnil |
| Číst | GET /files/activity | Co se v daném období vytvořilo, změnilo nebo smazalo |
| Číst | GET /history | Historie změn |
| Číst | GET /search?q=… | Nalezené řádky: path, line, text |
| Číst | GET /meetings, GET /meetings/:id | Schůzky a jedna schůzka |
| Navrhovat změny | POST /proposals | Návrh změn nejvýš 50 souborů, čeká na schválení |
| Navrhovat změny | POST /notes | Nová poznámka jako návrh, čeká na schválení |
Na cokoli jiného dostane token odpověď 403, na jiný brain 404 a zrušený nebo vypršelý token 401.
Popis API (OpenAPI)
Všechny tyto požadavky i těla webhooků jsou popsané ve strojově čitelném popisu OpenAPI: parametry a jejich limity, ukázky požadavků, tvar odpovědí a kódy chyb každého požadavku.
- OpenAPI: https://api.onlybrain.ai/v1/openapi/integrations.json
- Swagger UI: https://api.onlybrain.ai/docs/integrations, kde jde požadavky rovnou vyzkoušet s tokenem (tlačítko Authorize)
Adresu OpenAPI jde načíst do Postmanu, Insomnie nebo generátoru klienta. Těla webhooků jsou v popisu v sekci x-webhooks a ve Swagger UI mezi schématy dole (např. BrainChangedEventDto).
Limity a chyby
- Nejvýš 60 požadavků za minutu na jeden token.
- Nejvýš 30 návrhů a poznámek za hodinu na jeden token.
- Po překročení přijde odpověď
429s hlavičkouRetry-After: počet sekund, po kterých jde požadavek zopakovat.
Chyba má vždy stejný tvar, code je stálý kód pro program a message věta pro člověka:
{ "error": { "code": "FORBIDDEN", "message": "..." } }Zprávy jsou česky. S hlavičkou Accept-Language: en přijdou anglicky.
Webhooky
Webhook je opačný směr: onlybrain sám pošle jiné službě zprávu, když se v brainu něco stane (nová změna, návrh ke schválení, rozhodnutí o návrhu, hotová schůzka, nový nebo odebraný člen). Nastavují ho správci brainu v Nastavení v sekci Webhooky. Ve zprávě jsou jen údaje o události, obsah souborů nikdy. Když služba potřebuje obsah, přečte si ho tokenem pro integraci.
Každá zpráva nese hlavičky:
X-Onlybrain-Signature:sha256=a HMAC-SHA256 těla zprávy v hexadecimálním zápisu, podepsaný tajemstvím webhooku (whsec_…, zobrazí se jen jednou při přidání webhooku),X-Onlybrain-Event: druh události, např.brain.changed,X-Onlybrain-Delivery: číslo doručení, při dalším pokusu o stejné doručení se nemění,X-Onlybrain-Timestamp: čas tohoto pokusu v sekundách (unixový čas).
Tělo zprávy je vždy { id, event, createdAt, brain, data }. Pole id zůstává stejné i při opakování a po Poslat znovu, podle něj jde poznat zprávu, která už jednou došla.
Ověření podpisu v Node.js. Podepisuje se tělo přesně tak, jak přišlo, ne znovu převedený 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))
}Zprávu s neplatným podpisem je potřeba zahodit. Podrobný popis událostí a jejich obsahu je v popisu OpenAPI (sekce x-webhooks) a v dokumentaci API.
Bezpečně
- Dát tokenu jen to, co služba opravdu potřebuje. Na přehledy a reporty stačí Číst.
- Token ukládat jen do správce hesel nebo přihlašovacích údajů služby, nikdy do brainu, do kódu v repozitáři ani do sdíleného dokumentu.
- Pro každou službu vytvořit vlastní token. Při problému jde zrušit jen ten jeden.
- Jednou za čas projít v Nastavení → Integrace, kdy se který token naposledy použil, a nepoužívané zrušit.