Om voor klanten een alternatief te bieden voor crawling hebben we enkele endpoints beschikbaar gesteld om zo vanuit externe bronnen informatie met ons platform te delen, of vanuit ons platform te lezen. Deze endpoints zijn primair voor het lezen, schrijven, bijwerken en verwijderen van de zogeheten Documenten.
Documenten
Binnen het platform zijn Documenten de bronnen waaruit wij antwoorden genereren. Alle documenten voor een klant bijelkaar noemen wij de kennisbank. Met de API heeft een externe partij invloed op deze kennisbank en daarmee de kwaliteit van de gegenereerde antwoorden.
Authenticatie
Om HTTP-verzoeken naar ons systeem te authoriseren gebruiken we een zogeheten ‘long lived Bearer token’.
Wij zijn in staat tokens te beheren met alle permissies, maar ook met een selectie van deze permissies.
Bijvoorbeeld: Als een openbare service alleen gemachtigd moet zijn om informatie op te vragen, dat al is aangemaakt door een andere strategie of token.
Voorbeeld van Authorization-header met een Bearer-token:
Authorization: Bearer 31090db4198c2bf9f9a7d768bf6107a40f102d47534cb122b0
Aan deze authenticatie-token verlenen wij de volgende (CRUD-)permissies:
documents:create
documents:read
documents:update
documents:delete
API Documentatie
Algemene informatie en uitgangspunten
De API is een combinatie van het JSON:API standaard bovenop een REST-architectuur.
Dit heeft als voordeel dat de URL-structuur van de beschikbare endpoints en de request/response formats voorspelbaar zijn. De API verwacht hierom de volgende headers bij elke request:
Accept: application/vnd.api+json
Content-Type: application/vnd.api+json
Alle endpoints zijn per klant beschikbaar onder een eigen sub-domein,
bijvoorbeeld: https://{klant}.vragen.ai/api/v1/
In antwoorden vanuit de API vind je de property content_cleaned terug.
Hierin vind je de opgeslagen content terug dat door onze filter en parser is gegaan, t.b.v. verdere verwerking. Hiermee kan worden gevalideerd of de verzonden informatie goed wordt verwerkt.
Document Schema
De volgende informatie kan worden meegegeven per document:
url
Elke document moet een unieke bron-URL hebben.
Hiermee maken we elk document uniek en te onderscheiden.
external_reference (optioneel)
Een optionele referentie naar een identifier binnen het externe systeem.
mime_type
Momenteel ondersteunen wij HTML en PDF bronnen: text/html of application/pdf
meta_data
Wij gebruiken meta_data om een ‘correcte’ datum van het de bron aan te merken.
Indien aanwezig lezen wij hier author en date uit.
Daarnaast heb je hier de vrijheid extra informatie mee te geven aan het document.
Doel hiervan is bijvoorbeeld maatwerk te ondersteunen binnen externe systemen.
title
De titel van de bron.
content
De inhoud van de bron dat we verwerken en primair gebruiken binnen de kennisbank.
Let op
In het geval van "mime_type": "text/html" verwachten wij zo compleet mogelijke en een valide HTML.
Geef content altijd binnen valide HTML tags:<html><body> ... </body></html>
{
"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
Creëren van een nieuw document
POST https://{klant}.vragen.ai/api/v1/documents
Voorbeeld 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"
}
}
}
}
Voorbeeld 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"
}
}
}
Lezen van een bestaand document
GET https://{klant}.vragen.ai/api/vi/documents/{document_id}
Voorbeeld Response (vergelijkbaar met 'Creeren van 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"
}
}
}
Bijwerken van een bestaand document
PATCH https://{klant}.vragen.ai/api/v1/documents/{document_id}
Voorbeeld 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"
}
}
}
}
Voorbeeld 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"
}
}
}
Lezen van alle aanwezige documenten
GET https://{klant}.vragen.ai/api/v1/documents
Voorbeeld 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"
}
},
...
]
}
Het antwoord zal een lijst van documenten bevatten, indien aanwezig. Structuur van deze objecten zijn hetzelfde per document en vergelijkbaar met wanneer je een enkel document opvraagt.
Let op: met de volgende informatie dat je zal terugkrijgen kan je opvolgende verzoeken sturen om verdere informatie op te halen
{
...
"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"
},
...
}
Verwijderen van een document
DELETE https://{klant}.vragen.ai/api/v1/documents/{document_id}
Support
Aan de hand van bovenstaande informatie en voorbeelden zou je geen problemen moeten ondervinden om een verbinding op te zetten met onze API. Als je nog vragen hebt, neem dan contact op met ons supportteam via support@vragen.ai.
