API pentru asistentul AI

Ce faceCopiază linkul

API-ul asistentului rulează același asistent AI ca aplicația Brivio, prin API-ul public: deschizi o conversație, trimiți un mesaj și primești răspunsul, ca JSON sau în flux, cu Server-Sent Events. Asistentul citește datele organizației cu permisiunile persoanei din spatele credențialului tău.

Asistentul nu modifică nimic singur. Când vrea să creeze sau să schimbe ceva, modificarea devine o propunere pe care persoana o aprobă în aplicația Brivio, în Fluxul de aprobări. Aprobarea nu este posibilă prin API, cu niciun credențial. Poți lista propunerile în așteptare și le poți respinge.

Credențiale și scope-uriCopiază linkul

• Un token OAuth acționează pentru utilizatorul care l-a acordat.
• O cheie API acționează pentru membrul care a creat-o. Dacă persoana pleacă din organizație, cheia nu mai funcționează pentru asistent de la următoarea cerere.
• Scope-uri: assistant:read (conversații, propuneri) și assistant:write (o întrebare, o conversație nouă, respingerea unei propuneri). Fiecare întrebare consumă credit AI din portofelul organizației și se socotește în bugetele AI.

Endpoint-uriCopiază linkul

Id-urile conversațiilor și ale propunerilor sunt numere întregi pozitive. O conversație care nu este a ta întoarce 404.

Webhook-uriCopiază linkul

Abonează un webhook la assistant.proposal.created și assistant.proposal.resolved ca să afli când un tur lasă o propunere și când aceasta este aprobată, eșuează, este respinsă sau expiră — fără interogări periodice. Payload-urile conțin identificatori, numele instrumentului și approve_url, niciodată datele instrumentului. Vezi Webhook-uri.

O întrebareCopiază linkul

curl -X POST https://api.brivio.ro/v1/assistant/threads/42/runs \
  -H "Authorization: Bearer $BRIVIO_KEY" -H "Content-Type: application/json" \
  -d '{"message":"Câte facturi sunt restante?","locale":"ro"}'

În data primești text, status (completed, pending_approval sau refused), pending_approvals (fiecare cu approve_url) și usage. Fiecare răspuns are antetul X-Brivio-AI: generated; reviewed=none; model=codai: textul este generat de AI și nu a fost verificat de o persoană.

În fluxCopiază linkul

Trimite "stream": true (sau Accept: text/event-stream) și citește evenimentele: text cu { "delta": "…" }, apoi done cu răspunsul complet, sau error. Erorile de buget, de limită și de validare vin înainte să se deschidă fluxul, ca JSON obișnuit (402, 422, 429).

SDK-uri, CLI, MCPCopiază linkul

• TypeScript: brivio.assistant.runs.create(...) / brivio.assistant.runs.stream(...).
• PHP: createAssistantRun($threadId, ['message' => '…']) (doar JSON).
• CLI: brivio assistant ask "Câte facturi sunt restante?" (în flux, implicit).
• MCP: unealta brivio_ask_assistant, pentru Claude, ChatGPT sau orice client MCP — și pe serverul găzduit doar pentru citire, pentru că o întrebare doar propune modificări. Configurare: Brivio în Claude și ChatGPT.

Unelte HTTP personalizateCopiază linkul

Un administrator poate conecta API-ul tău ca unealtă a asistentului din Asistent → Unelte (permisiunea assistant.extend). Fiecare apel cere aprobarea utilizatorului în chat, sunt permise doar gazde publice HTTPS, iar secretul e injectat pe server ca {{secret}} într-un header.

JSON Schema opțională pentru intrare devine input-ul tipizat al uneltei. Rădăcina trebuie să fie un object și poate folosi string (cu enum, maxLength), number / integer (cu minimum, maximum), boolean, object imbricat (cu properties, required) și array (cu schemă items și maxItems). Limite: 4 niveluri de imbricare, 50 de proprietăți pe obiect, 100 de elemente pe listă, 200 de noduri. $ref, oneOf / anyOf, additionalProperties, pattern și format nu sunt acceptate; o schemă neacceptată e refuzată la salvare, cu calea care a picat.

Endpoint-ul tău primește doar cheile declarate de schemă, la orice nivel: orice altceva adaugă modelul e eliminat și apare în rezultat la droppedArguments (de exemplu lines[0].notes). POST, PUT și PATCH trimit JSON; GET trimite query string, cu valorile imbricate codificate JSON.