Product

Oplossingen

Hulpbronnen

Over ons

Contact

Login

Stel een vraag

Demo aanvragen

Introductie

Wat is vragen.ai?

Terminologie

Aan de slag

Kennisbeheer

Vragen.ai crawler

Crawler whitelisten in Cloudflare

Drupal Search API Module

Koppelen met API

Configuratie

Vragen.ai configureren

Best practices

Integraties

Vragen.ai integreren in je website

Veelgestelde vragen

Evaluatiescores in jouw inbox

Technische issues oplossen

Introductie

Wat is vragen.ai?

Terminologie

Aan de slag

Kennisbeheer

Vragen.ai crawler

Crawler whitelisten in Cloudflare

Drupal Search API Module

Koppelen met API

Configuratie

Vragen.ai configureren

Best practices

Integraties

Vragen.ai integreren in je website

Veelgestelde vragen

Evaluatiescores in jouw inbox

Technische issues oplossen

Introductie

Wat is vragen.ai?

Terminologie

Aan de slag

Kennisbeheer

Vragen.ai crawler

Crawler whitelisten in Cloudflare

Drupal Search API Module

Koppelen met API

Configuratie

Vragen.ai configureren

Best practices

Integraties

Vragen.ai integreren in je website

Veelgestelde vragen

Evaluatiescores in jouw inbox

Technische issues oplossen

Koppelen met API

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

  1. 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

  2. Alle endpoints zijn per klant beschikbaar onder een eigen sub-domein,
    bijvoorbeeld: https://{klant}.vragen.ai/api/v1/

  3. 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

Wanneer je documenten toevoegt aan de kennisbank, kun je de volgende informatie meegeven:

Basis velden

external_reference

Type: string (verplicht)

Een referentie naar het document binnen je eigen systeem. Gebruik dit veld om een koppeling te maken tussen documenten in de kennisbank en records in je eigen database of CMS.

url

Type: string (verplicht)

De unieke bron-URL van het document. Hiermee maken we elk document uniek en onderscheidbaar binnen de kennisbank. Zorg ervoor dat elke URL uniek is per document.

mime_type

Type: string (verplicht)

Het bestandstype van de bron. Momenteel ondersteunen we de volgende types:

  • text/html voor HTML-documenten

  • application/pdf voor PDF-bestanden

title

Type: string (optioneel, maar aanbevolen)

De titel van het document. Deze wordt gebruikt voor weergave in zoekresultaten en helpt gebruikers het document te identificeren.

Automatische extractie: Als je geen titel meegeeft, halen we automatisch de titel uit het document zelf (bijvoorbeeld uit een <h1> tag bij HTML-documenten).

content

Type: string (optioneel)

De volledige tekstinhoud van het document. Deze content wordt geïndexeerd en vormt de basis voor het doorzoeken van de kennisbank.

Automatische download: Als je geen content meegeeft, downloaden we automatisch het document op basis van de opgegeven URL en extraheren we de content. Dit is handig wanneer je niet zelf de content wil ophalen en extraheren.

Let op
In het geval van "mime_type": "text/html" verwachten wij zo compleet mogelijke en een valide HTML.

Geef content altijd binnen volledige HTML tags: <html><body> ... </body></html>

Extra velden

meta_data

Type: object (optioneel)

Een flexibel object voor aanvullende metadata die het gedrag van de kennisbank en zoekresultaten kan verrijken. Je bent volledig vrij om hier eigen velden aan toe te voegen. Deze metadata wordt gebruikt om de systemen slimmer te maken en kan ingezet worden om zoekresultaten te verrijken.

Veelgebruikte meta_data velden (voorbeelden):

Hoewel er geen voorgeschreven structuur is, worden de volgende velden vaak gebruikt en herkend door het systeem:

  • author (string) - De auteur of maker van het document

  • date (string, ISO 8601 formaat) - Publicatie- of wijzigingsdatum van het document. Deze datum kan worden gebruikt om de actualiteit van bronnen te bepalen.

  • language (string, ISO 639-1 code) - De taal van het document (bijv. "nl", "en")

  • category (string) - Categorisering van het document (bijv. "productdocumentatie", "blogpost", "handleiding")

Gebruik van custom velden:

Je kunt volledig vrij eigen metadata velden toevoegen die specifiek zijn voor jouw use case. Deze custom velden kunnen worden gebruikt voor:

  • Maatwerk functionaliteit binnen systemen

  • Slimmer maken van je Agent en Antwoordsysteem

  • Filtering en facettering van zoekresultaten

  • Verrijken van je zoekresultaten


{
  "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 info@vragen.ai.

 

Privacy statement

vragen.ai is een product van

Stel een vraag

Demo aanvragen

Stel een vraag

Demo aanvragen