Docs / API

Werken met de API

vragen.ai heeft een API waarmee je vanuit je eigen systemen je kennisbank vult, doorzoekt en analyseert. Deze pagina beschrijft de basis die voor alle API-pagina's geldt: de base-URL, de authenticatie, de vaste headers en de JSON:API-conventies. De taakgerichte pagina's bouwen hierop voort:

• Koppelen met API: documenten aanmaken, bijwerken en verwijderen.
• Zoeken via de API: semantisch zoeken en vergelijkbare content ophalen.
• Analyseren via de API: gesprekken en vragen ophalen voor analyse.
• Deployments ophalen via de API: de widget-varianten in je omgeving opvragen.

Wil je je kennisbank aan een AI-client zoals Claude koppelen, dan kan dat ook via de kennisbank als MCP-server.

Base-URL

Alle endpoints zijn per klant beschikbaar onder je eigen subdomein:

https://{klant}.vragen.ai/api/v1/

Authenticatie

Om verzoeken te authoriseren gebruiken we een long-lived Bearer-token. Je stuurt het mee in de Authorization-header:

Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0

Tokens beheer je in je vragen.ai-omgeving. Een token kan alle permissies krijgen of een selectie ervan. Zo geef je een openbare dienst die alleen mag lezen bijvoorbeeld enkel documents:read, terwijl een koppeling die de kennisbank bijwerkt ook documents:create, documents:update en documents:delete krijgt.

Vaste headers

De API volgt de JSON:API-standaard bovenop een REST-architectuur. Daardoor zijn de URL-structuur en de request- en response-vorm voorspelbaar. Stuur bij elk verzoek deze headers mee:

• Accept: application/vnd.api+json
• Content-Type: application/vnd.api+json

JSON:API-conventies

Deze parameters werken op alle endpoints hetzelfde. De taakpagina's vermelden per resource welke waarden geldig zijn.

• fields[<type>] (sparse fieldsets): beperk de teruggegeven velden per resourcetype, bijvoorbeeld fields[documents]=title,url. Zo houd je responses klein.
• include: laad gerelateerde resources in dezelfde response mee, bijvoorbeeld include=runs.
• filter[...]: filter de resultaten. De opbouw verschilt per resource; zie de betreffende pagina.
• sort: sorteer op een veld, met een - ervoor voor aflopend, bijvoorbeeld sort=-created_at.
• Paginering met page[offset] en page[limit]: page[offset] is het aantal over te slaan items (niet het paginanummer), page[limit] het aantal per pagina.

Foutmeldingen

Gaat er iets mis, dan krijg je een passende HTTP-statuscode en een JSON:API-foutobject terug:

{
  "errors": [
    {
      "status": "400",
      "title": "Bad request",
      "detail": "The url field is required."
    }
  ]
}

Rate limiting

Om het platform stabiel te houden is de API begrensd in het aantal verzoeken per minuut. Hoeveel dat er precies zijn, hangt af van je abonnement. Overschrijd je de limiet, dan krijg je een 429 Too Many Requests-response met een Retry-After-header die aangeeft na hoeveel seconden je het opnieuw kunt proberen. De actuele stand lees je af aan de X-RateLimit-Limit- en X-RateLimit-Remaining-headers van elke response.

Verwacht je structureel meer verkeer? Neem contact op via service@vragen.ai.

De resources in het kort

Support

Kom je er niet uit? Mail ons supportteam via service@vragen.ai.