API Documentatie

Gebruik PrivaAI via de webapp of via private integraties op aanvraag. Deze documentatie legt uit welke acties beschikbaar zijn en welke verantwoordelijkheden bij de gebruiker blijven.

Basis URL: https://privaai.nl/api· Private integraties · Fair-use limieten · Org-scoped toegang

Authenticatie

De endpoints op deze pagina zijn in productie primair bedoeld voor de PrivaAI webapp en gebruiken een ingelogde sessie. Private server-to-server integraties worden per organisatie geactiveerd.

API keys kun je beheren in PrivaAI Compliance via Instellingen → API Keys, met fair-use limieten per uur, dag en maand.

http

Cookie: privaai_session=<ingelogde_sessie_cookie>

Voorbeeld: cURL

bash

curl https://privaai.nl/api/chat \
  -H "Cookie: privaai_session=<ingelogde_sessie_cookie>" \
  -H "Content-Type: application/json" \
  -d '{"messages": [{"role": "user", "content": "Hallo!"}]}'

Voorbeeld: JavaScript

javascript

const response = await fetch('https://privaai.nl/api/chat', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    messages: [{ role: 'user', content: 'Hallo!' }]
  })
});

// Response is a text stream
const reader = response.body.getReader();
const decoder = new TextDecoder();
let text = '';

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  text += decoder.decode(value);
  console.log(decoder.decode(value)); // stream tokens as they arrive
}

Chat

POST/api/chat

Stuur berichten naar PrivaAI. Antwoorden worden als tekststream teruggestuurd. PrivaAI kiest intern de juiste routing en gebruikt automatisch je organisatiekennisbank (RAG) als die documenten bevat.

Request body

Parameter	Type	Beschrijving
`messages`*	`array`	Array van {role: "user"\|"assistant", content: "string"} objecten
`conversationId`	`string`	ID van een bestaand gesprek om door te gaan. Leeg = nieuw gesprek.

Response headers

Parameter	Type	Beschrijving
`X-Conversation-Id`	`string`	ID van het (nieuwe) gesprek. Sla op voor vervolggesprekken.
`X-RAG-Context`	`boolean`	"true" als kennisbank context gebruikt is.

json

// Request
{
  "messages": [
    { "role": "user", "content": "Wat is ons retourbeleid?" }
  ]
}

// Response: text/plain stream
"Op basis van je bedrijfsdocumenten: het retourbeleid is..."
(streamed token by token)

Gesprekken

GET/api/conversations

Lijst van je eigen recente gesprekken (max 50).

json

{
  "conversations": [
    {
      "id": "uuid",
      "title": "Wat is ons retourbeleid?",
      "createdAt": "2026-03-30T12:00:00Z",
      "updatedAt": "2026-03-30T12:05:00Z"
    }
  ]
}

GET/api/conversations/:id

Geeft gesprek + alle berichten terug.

DELETE/api/conversations/:id

Verwijdert gesprek en alle bijbehorende berichten.

Documenten

GET/api/documents

Lijst van documenten in de kennisbank van je organisatie.

json

{
  "documents": [
    {
      "id": "uuid",
      "filename": "retourbeleid.pdf",
      "status": "ready",
      "sizeBytes": 45230,
      "createdAt": "2026-03-28T10:00:00Z"
    }
  ]
}

POST/api/documents/upload

Upload een document naar de kennisbank. Gebruik multipart/form-data.

bash

curl https://privaai.nl/api/documents/upload \
  -H "Cookie: privaai_session=<ingelogde_sessie_cookie>" \
  -F "file=@retourbeleid.pdf"

// Response
{
  "id": "uuid",
  "filename": "retourbeleid.pdf",
  "status": "processing",
  "size": 45230
}

// Poll status:
GET /api/documents/{id}/status

Parameter	Type	Beschrijving
`file`*	`File`	PDF, DOCX, TXT, CSV of MD. Max 25MB.

POST/api/documents/text

Voeg geplakte tekst direct toe aan de kennisbank zodat gebruikers deze later kunnen terugvinden en gebruiken als context in chat en co-workers.

json

{
  "title": "Retourbeleid",
  "text": "Klanten kunnen binnen 14 dagen..."
}

Parameter	Type	Beschrijving
`title`	`string`	Naam voor het kennisbankdocument. Standaard: Geplakte tekst.
`text`*	`string`	Minimaal 10 tekens, maximaal 200.000 tekens.

POST/api/documents/search

Zoek semantisch in de kennisbank van je organisatie. Resultaten zijn org-scoped en kunnen worden beperkt tot specifieke document-ID's.

json

// Request
{
  "query": "Wat staat er in ons retourbeleid?",
  "topK": 5,
  "documentIds": ["uuid"]
}

// Response
{
  "query": "Wat staat er in ons retourbeleid?",
  "results": [
    {
      "documentId": "uuid",
      "score": 0.82,
      "content": "Klanten kunnen binnen 14 dagen..."
    }
  ]
}

Parameter	Type	Beschrijving
`query`*	`string`	Zoekvraag van minimaal 3 tekens.
`topK`	`number`	Aantal resultaten, 1 t/m 20. Standaard 5.
`documentIds`	`array`	Optionele documentfilter binnen dezelfde organisatie.

GET/api/documents/:id

Geeft documentmetadata en verwerkingsstatus terug. Gebruik dit vooral om te controleren of een document klaar is voor gebruik.

json

{
  "document": {
    "id": "uuid",
    "filename": "retourbeleid.pdf",
    "status": "ready"
  }
}

GET/api/documents/:id/status

Controleer de verwerkingsstatus van een document. Poll elke 2 seconden totdat status ready of failed is.

json

{
  "id": "uuid",
  "status": "ready",
  "indexed": true,
  "errorMessage": null
}

DELETE/api/documents/:id

Verwijdert het document en bijbehorende kennisbankgegevens voor je organisatie.

Hoe gebruikers de kennisbank gebruiken

Upload beleid, contracten, procedures of veelgebruikte antwoorden.
Wacht tot het document klaarstaat voordat je het in chat of co-workers gebruikt.
Stel vragen met broncontext, bijvoorbeeld “wat zegt ons beleid over bewaartermijnen?”.
Gebruik documentfilters als je alleen op één dossier of document wilt werken.
Controleer AI-antwoorden voordat je ze gebruikt voor advies, besluitvorming of externe communicatie.
Beheer oude of verkeerde documenten actief, zodat gebruikers geen verouderde broninformatie gebruiken.

Foutcodes

Code	Betekenis
`400`	Ongeldig verzoek — controleer je request body
`401`	Niet ingelogd of geen geldige integratie-auth
`403`	Geen toegang of werkruimte is nog niet volledig ingericht
`404`	Resource niet gevonden
`429`	Rate limit of fair-use limiet bereikt — vertraag je verzoeken
`500`	Server fout — probeer opnieuw of neem contact op

Alle foutresponses hebben het formaat: {"error": "beschrijving"}

Rate Limits

Plan	Fair use	Max bestandsgrootte
Solo	250.000 tokens/maand, geen API keys	25 MB
Team	1.500.000 tokens/maand, geen API keys	25 MB
Compliance	5.000.000 tokens/maand + API keys	25 MB

Meer API-volume nodig?

API-toegang is beschikbaar vanaf het Compliance-plan. Neem contact op voor hoge volumes, aanvullende afspraken of custom integraties. Wij bouwen mee aan jouw gebruik.

Contact opnemen