To offer customers an alternative to crawling, we have made several endpoints available to share information with our platform from external sources or to read from our platform. These endpoints are primarily for reading, writing, updating, and deleting the so-called Documents.
Documents
Within the platform, Documents are the sources from which we generate answers. All documents for a customer combined are called the knowledge base. With the API, an external party can influence this knowledge base and thereby the quality of the generated answers.
Authentication
To authorize HTTP requests to our system, we use a so-called 'long lived Bearer token'.
We are capable of managing tokens with all permissions, but also with a selection of these permissions.
Example: If a public service only needs authorization to request information that has already been created by another strategy or token.
Example of an Authorization header with a Bearer token:
Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0
We grant the following (CRUD) permissions to this authentication token:
documents:create
documents:read
documents:update
documents:delete
API Documentation
General Information and Principles
The API is a combination of the JSON:API standard on top of a REST architecture.
This has the advantage that the URL structure of the available endpoints and the request/response formats are predictable. The API therefore expects the following headers with each request:
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
All endpoints are available per customer under their own subdomain,
for example: https://{klant}.vragen.ai/api/v1/
In responses from the API, you will find the property content_cleaned.
This contains the stored content that has been filtered and parsed by us, for further processing. This allows you to verify whether the sent information is processed correctly.
Document Schema
When you add documents to the knowledge base, you can provide the following information:
Basic Fields
external_reference
Type: string (required)
A reference to the document within your own system. Use this field to link documents in the knowledge base with records in your own database or CMS.
url
Type: string (required)
The unique source URL of the document. This makes each document unique and distinguishable within the knowledge base. Ensure that each URL is unique per document.
mime_type
Type: string (required)
The file type of the source. We currently support the following types:
text/html for HTML documents
application/pdf for PDF files
title
Type: string (optional, but recommended)
The title of the document. This is used for display in search results and helps users identify the document.
Automatic Extraction: If you do not provide a title, we automatically extract the title from the document itself (for example, from an <h1> tag in HTML documents).
content
Type: string (optional)
The full text content of the document. This content is indexed and forms the basis for searching the knowledge base.
Automatic Download: If you do not provide content, we automatically download the document based on the given URL and extract the content. This is useful when you do not want to retrieve and extract the content yourself.
Note
In the case of "mime_type": "text/html" we expect as complete as possible and valid HTML.
Always provide content within complete HTML tags: <html><body> ... </body></html>
Additional Fields
meta_data
Type: object (optional)
A flexible object for additional metadata that can enrich the behavior of the knowledge base and search results. You are completely free to add your own fields here. This metadata is used to make the systems smarter and can be used to enrich search results.
Commonly Used meta_data Fields (Examples):
Although there is no prescribed structure, the following fields are often used and recognized by the system:
author (string) - The author or creator of the document
date (string, ISO 8601 format) - Publication or modification date of the document. This date can be used to determine the currency of sources.
language (string, ISO 639-1 code) - The language of the document (e.g., "nl", "en")
category (string) - Categorization of the document (e.g., "product documentation", "blog post", "manual")
Use of Custom Fields:
You can freely add your own metadata fields that are specific to your use case. These custom fields can be used for:
Custom functionality within systems
Making your Agent and Answer System smarter
Filtering and faceting of search results
Enriching your search results
{
"data": {
"external_reference": "scrapedPage:9001",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/over-ons",
"mime_type": "text/html",
"title": "Over ons",
"content": "<html><body><p>Hallo wereld!</p></body></html>"
"meta_data": {
"date": "2024-12-12T12:00:00+00:00"
}
}
}{
"data": {
"external_reference": "scrapedPage:9001",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/over-ons",
"mime_type": "text/html",
"title": "Over ons",
"content": "<html><body><p>Hallo wereld!</p></body></html>"
"meta_data": {
"date": "2024-12-12T12:00:00+00:00"
}
}
}{
"data": {
"external_reference": "scrapedPage:9001",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/over-ons",
"mime_type": "text/html",
"title": "Over ons",
"content": "<html><body><p>Hallo wereld!</p></body></html>"
"meta_data": {
"date": "2024-12-12T12:00:00+00:00"
}
}
}
Endpoints
Creating a New Document
POST https://{klant}.vragen.ai/api/v1/documents
Example Request Body:
{
"data": {
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"title": "Homepage",
"content": "<html><body><p>SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren</p></body></html>",
"external_reference": "foo_1",
"mime_type": "text/html",
"meta_data": {
"author": "SWIS"
}
}
}
}{
"data": {
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"title": "Homepage",
"content": "<html><body><p>SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren</p></body></html>",
"external_reference": "foo_1",
"mime_type": "text/html",
"meta_data": {
"author": "SWIS"
}
}
}
}{
"data": {
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"title": "Homepage",
"content": "<html><body><p>SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren</p></body></html>",
"external_reference": "foo_1",
"mime_type": "text/html",
"meta_data": {
"author": "SWIS"
}
}
}
}Example Response
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS"
},
"content_cleaned": "..."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS"
},
"content_cleaned": "..."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS"
},
"content_cleaned": "..."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}Reading an Existing Document
GET https://{klant}.vragen.ai/api/vi/documents/{document_id}
Example Response (similar to 'Creating a Document'):
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foobar_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "html",
"title": "Homepage",
"meta_data": null,
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foobar_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "html",
"title": "Homepage",
"meta_data": null,
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foobar_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "html",
"title": "Homepage",
"meta_data": null,
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}
Updating an Existing Document
PATCH https://{klant}.vragen.ai/api/v1/documents/{document_id}
Example Request Body:
{
"data": {
"id": "9001",
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"external_reference": "foo_1",
"mime_type": "text/html",
"title": "Homepage",
"content": "SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren",
"meta_data": {
"author": "SWIS - test"
}
}
}
}{
"data": {
"id": "9001",
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"external_reference": "foo_1",
"mime_type": "text/html",
"title": "Homepage",
"content": "SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren",
"meta_data": {
"author": "SWIS - test"
}
}
}
}{
"data": {
"id": "9001",
"type": "documents",
"attributes": {
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"external_reference": "foo_1",
"mime_type": "text/html",
"title": "Homepage",
"content": "SWIS heeft alles in huis om te ontdekken wat je organisatie nodig heeft om digitaal succesvol te worden. En blijven. Ontdekken wat je echt nodig hebt. Vanuit een succesvolle strategie bedenken en ontwerpen we een oplossing. Meer over ontdekken Maken wat het meest waardevol is. Onze agile teams weten precies hoe je zo’n oplossing maakt. In een slim, snel en soepel proces. Meer over maken. Optimaliseren om succesvol te blijven. Daarvoor moet je aan de knoppen van je product of dienst blijven draaien. Wij helpen je daarbij. Meer over optimaliseren",
"meta_data": {
"author": "SWIS - test"
}
}
}
}Example Response:
{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS - test"
},
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS - test"
},
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}{
"jsonapi": {
"version": "1.0"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
},
"data": {
"type": "documents",
"id": "9001",
"attributes": {
"external_reference": "foo_1",
"url": "https://domein-met-het-nieuwe-zoeken.nl",
"mime_type": "text/html",
"title": "Homepage",
"meta_data": {
"author": "SWIS - test"
},
"content_cleaned": "This is alle content van de pagina."
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/9001"
}
}
}Reading All Available Documents
GET https://{klant}.vragen.ai/api/v1/documents
Example Response Body
{
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
"data": [
{
"type": "documents",
"id": "1",
"attributes": {
"external_reference": "scrapedPage:119145",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/nieuws",
"mime_type": "text/html",
"title": "Actueel | Het Nieuwe Zoeken",
"meta_data": {
"date": "2023-07-19T12:00:00+00:00"
},
"content_cleaned": "Vandaag beginnen zoeken wij anno 2024"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/1"
}
},
...
]
}{
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
"data": [
{
"type": "documents",
"id": "1",
"attributes": {
"external_reference": "scrapedPage:119145",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/nieuws",
"mime_type": "text/html",
"title": "Actueel | Het Nieuwe Zoeken",
"meta_data": {
"date": "2023-07-19T12:00:00+00:00"
},
"content_cleaned": "Vandaag beginnen zoeken wij anno 2024"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/1"
}
},
...
]
}{
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"jsonapi": {
"version": "1.0"
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
"data": [
{
"type": "documents",
"id": "1",
"attributes": {
"external_reference": "scrapedPage:119145",
"url": "https://www.domein-met-het-nieuwe-zoeken.nl/nieuws",
"mime_type": "text/html",
"title": "Actueel | Het Nieuwe Zoeken",
"meta_data": {
"date": "2023-07-19T12:00:00+00:00"
},
"content_cleaned": "Vandaag beginnen zoeken wij anno 2024"
},
"links": {
"self": "https://{klant}.vragen.ai/api/v1/documents/1"
}
},
...
]
}The answer will contain a list of documents, if available. The structure of these objects is the same per document and similar to when you request a single document.
Note: With the following information that you will return, you can send subsequent requests to retrieve further information
{
...
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
...
}
{
...
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
...
}
{
...
"meta": {
"page": {
"currentPage": 1,
"from": 1,
"lastPage": 901,
"perPage": 10,
"to": 10,
"total": 9001
}
},
"links": {
"first": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=1&page%5Bsize%5D=10",
"last": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=634&page%5Bsize%5D=10",
"next": "https://{klant}.vragen.ai/api/v1/documents?page%5Bnumber%5D=2&page%5Bsize%5D=10"
},
...
}
Deleting a Document
DELETE https://{klant}.vragen.ai/api/v1/documents/{document_id}
Support
Based on the above information and examples, you should not encounter any issues setting up a connection with our API. If you have further questions, please contact our support team via info@vragen.ai.
