Docs / API

Working with the API

vragen.ai has an API that lets you fill, search and analyze your knowledge base from your own systems. This page covers the basics that apply to all API pages: the base URL, authentication, the required headers and the JSON:API conventions. The task-oriented pages build on this:

• Connecting via the API: creating, updating and deleting documents.
• Searching via the API: semantic search and retrieving similar content.
• Analyzing via the API: retrieving conversations and questions for analysis.
• Retrieving deployments via the API: querying the widget variants in your environment.

If you want to connect your knowledge base to an AI client such as Claude, you can also do that via the knowledge base as an MCP server.

Base URL

All endpoints are available per customer under your own subdomain:

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

Authentication

Requests are authorized with a long-lived Bearer token. You send it in the Authorization header:

Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0

You manage tokens in your vragen.ai environment. A token can be granted all permissions or a selection of them. For example, you give a public service that only needs to read just documents:read, while an integration that updates the knowledge base also gets documents:create, documents:update and documents:delete.

Required headers

The API follows the JSON:API standard on top of a REST architecture. This makes the URL structure and the request and response format predictable. Send these headers with every request:

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

JSON:API conventions

These parameters work the same on all endpoints. The task pages list which values are valid for each resource.

• fields[<type>] (sparse fieldsets): limit the returned fields per resource type, for example fields[documents]=title,url. This keeps responses small.
• include: load related resources in the same response, for example include=runs.
• filter[...]: filter the results. The structure differs per resource; see the relevant page.
• sort: sort by a field, with a leading - for descending order, for example sort=-created_at.
• Pagination with page[offset] and page[limit]: page[offset] is the number of items to skip (not the page number), page[limit] the number per page.

Error messages

If something goes wrong, you get an appropriate HTTP status code and a JSON:API error object:

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

Rate limiting

To keep the platform stable, there is an upper bound on the number of requests per minute. That bound applies per token and per sender, and separately per environment: if one server integrates several vragen.ai environments, each environment gets its own budget. Search requests (search and similar) have their own, somewhat tighter bound, because a search is heavier than creating or updating a document. The bounds are generous: normal integration traffic, a full sync of your knowledge base included, does not come near them. They exist for outliers that would affect the service for others. If you exceed the limit, you get a 429 Too Many Requests response with a Retry-After header indicating after how many seconds you can try again. You can read the current status from the X-RateLimit-Limit and X-RateLimit-Remaining headers of every response.

Expecting structurally more traffic? Contact us at service@vragen.ai.

The resources at a glance

Support

Stuck? Email our support team at service@vragen.ai.