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.

Voordat je begint

De base-URL, de authenticatie met een Bearer-token en de vereiste headers staan op Werken met de API. Voor de acties op deze pagina heeft je token de permissies documents:create, documents:read, documents:update en documents:delete nodig.

API Documentatie

Algemene informatie en uitgangspunten

De API volgt de JSON:API-standaard bovenop REST; de base-URL en de vereiste headers staan op Werken met de API.

In antwoorden vind je daarnaast de property content_cleaned terug. Hierin staat de opgeslagen content nadat die door onze filter en parser is gegaan. Zo kun je valideren 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/v1/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": "text/html",
            "title": "Homepage",
            "meta_data": null,
            "content_cleaned": "Dit 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": "<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>",
            "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": "Dit 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

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

Niet gevonden wat je zocht?

Stel je vraag direct aan vragen.ai.

Je stelt je vraag aan een AI-assistent van vragen.ai. Antwoorden komen uit onze eigen content, met de bron erbij. Waarom we dit melden

Koppelen met API

Documenten

Voordat je begint

API Documentatie

Algemene informatie en uitgangspunten

Document Schema

Basis velden

external_reference

url

mime_type

title

content

Extra velden

meta_data

Veelgebruikte meta_data velden (voorbeelden):

Gebruik van custom velden:

Endpoints

Creëren van een nieuw document

Lezen van een bestaand document

Bijwerken van een bestaand document

Lezen van alle aanwezige documenten

Verwijderen van een document

Support

Niet gevonden wat je zocht?

`external_reference`

`url`

`mime_type`

`title`

`content`

`meta_data`

Veelgebruikte `meta_data` velden (voorbeelden):