Krok 7

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

  1. V brainu otevřít záložku Nastavení a sekci Integrace.
  2. Kliknout na Vytvořit token a vyplnit název, podle kterého půjde token později poznat (např. n8n: nové nabídky).
  3. Zaškrtnout Číst, Navrhovat změny nebo obojí a zvolit platnost.
  4. 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 Authorization a hodnotou Bearer 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žadavekCo vrátí nebo udělá
ČístGET /treeStrom souborů, které role vidí
ČístGET /file?path=…Obsah textového souboru (content) a jeho verzi (sha)
ČístGET /file/raw?path=…Soubor tak, jak je (PDF, obrázek, Office)
ČístGET /files/metaKdy soubory vznikly, kdy se naposledy změnily a kdo je měnil
ČístGET /files/activityCo se v daném období vytvořilo, změnilo nebo smazalo
ČístGET /historyHistorie změn
ČístGET /search?q=…Nalezené řádky: path, line, text
ČístGET /meetings, GET /meetings/:idSchůzky a jedna schůzka
Navrhovat změnyPOST /proposalsNávrh změn nejvýš 50 souborů, čeká na schválení
Navrhovat změnyPOST /notesNová 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.

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ěď 429 s hlavičkou Retry-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.