Documenten pushen vanuit jouw eigen systemen

De push-API indexeert documenten uit systemen waar Nordvec geen connector voor heeft: een export van een interne wiki, een ticketarchief, een database met notities. Jij stuurt de tekst en bepaalt wie deze mag lezen; Nordvec slaat het op in de EU, indexeert het en maakt het doorzoekbaar en citeerbaar zoals elk ander document. Elk gepusht document komt terecht in een gegevensbron, een benoemde container in jouw werkruimte die eerst door een beheerder van de werkruimte wordt aangemaakt. Een push die een niet-bestaande of gepauzeerde gegevensbron noemt, wordt geweigerd.

Open Instellingen werkruimte > Gegevensbronnen en kies Maak gegevensbron aan. Beheerders en eigenaren van de werkruimte kunnen dit doen; in een persoonlijke werkruimte ben jij dat.

De slug confluence-export wordt gebruikt in de onderstaande voorbeelden.

Pushes authenticeren met een API-sleutel van de Indexing-klasse die de index:write-scope bevat; voeg index:status toe om de opname te volgen en index:delete om documenten te verwijderen of een hele gegevensbron te vervangen. Maak er een aan onder Instellingen werkruimte > API-sleutels; de onbewerkte sleutel begint met nv_eu_idx_ en wordt één keer getoond. Zie Authentication. Elk verzoek vermeldt ook jouw werkruimte-id als tenantId, de id in het adres van jouw werkruimte in de app (/w/<workspace id>/...), en het moet de werkruimte zijn waartoe de sleutel behoort.

/documents/push maakt het document aan, of werkt het bij wanneer een document met dezelfde id al bestaat in de gegevensbron.

curl https://nordvec.com/api/v1/documents/push \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: page-4711-2026-09-28" \
  -d '{
    "tenantId": "YOUR_WORKSPACE_ID",
    "document": {
      "id": "page-4711",
      "title": "Travel expense policy",
      "datasource": "confluence-export",
      "body": { "mimeType": "text/markdown", "content": "# Travel expenses\n..." },
      "permissions": {},
      "sourceUrl": "https://wiki.example.com/pages/4711",
      "type": "policy"
    }
  }'

{ "documentId": "page-4711", "status": "queued", "updated": false }

• id is jouw stabiele id voor het document binnen de gegevensbron. Het opnieuw pushen van dezelfde id werkt het bij; ongewijzigde inhoud wordt herkend aan de hash en niet twee keer geïndexeerd.
• body.mimeType is een van text/plain, text/markdown, text/html, application/pdf, of de Word-, Excel- en PowerPoint-typen (.docx, .xlsx, .pptx). Binaire inhoud wordt base64-gecodeerd verzonden.
• sourceUrl wordt de "spring naar bron"-link bij elke citering van het document. Laat het weg bij een her-push om de opgeslagen link te behouden, of stuur null om deze te wissen.
• type stelt het content_type van het document in, waarop zoeken en lijsten filteren.

Het hele requestbody is begrensd tot 1 MB, dus een groot bestand of een grote batch antwoordt met 413; splits het.

permissions is vereist bij elke push, zodat er nooit een deelbeslissing wordt genomen door een veld weg te laten. In een gegevensbron die zichtbaar is voor de werkruimte:

Om te wijzigen wie een document mag lezen zonder de inhoud opnieuw te verzenden, gebruik je POST /documents/push/permissions. Het zichtbaar maken van een reeds beperkt document voor de hele werkruimte vereist bovendien de index:acl-widen-scope, zodat een routinematige synchronisatie een handmatig ingestelde beperking niet stilletjes kan ongedaan maken.

/documents/push/bulk accepteert tot 100 documenten voor één gegevensbron per oproep. Het antwoord telt accepted en rejected en geeft een resultaat per document, zodat één slecht document de batch niet laat mislukken. De limiet van 1 MB voor de body geldt per oproep, dus splits grote uploads in meerdere oproepen onder dezelfde uploadId.

curl https://nordvec.com/api/v1/documents/push/bulk \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tenantId": "YOUR_WORKSPACE_ID",
    "uploadId": "nightly-2026-09-28",
    "datasource": "confluence-export",
    "documents": [
      { "id": "page-4711", "title": "Travel expense policy", "datasource": "confluence-export",
        "body": { "mimeType": "text/plain", "content": "..." }, "permissions": {} }
    ]
  }'

Als jouw systeem alles kan opsommen wat een gegevensbron moet bevatten, stuur dan de volledige lijst als één uploadsessie, en de documenten die er niet meer in staan, worden naar de prullenbak verplaatst wanneer de sessie sluit. Sessies hebben een indexing API-sleutel nodig die zowel index:delete als index:write bevat, omdat het sluiten documenten verwijdert; de sleutel die een sessie opent, is de enige die deze kan voortzetten.

1. Stuur de eerste pagina met "isFirstPage": true. Dit is pagina 0.
2. Stuur elke volgende pagina met zijn pageIndex (1, 2, ...), in willekeurige volgorde. Een pagina die twee keer wordt verstuurd, telt één keer, dus een herhaling is altijd veilig.
3. Stuur de laatste pagina met "isLastPage": true en zijn pageIndex. Een lijst die in één pagina past, verstuurt isFirstPage en isLastPage samen. De laatste pagina mag geen documenten bevatten.

Elke pagina gebruikt dezelfde uploadId, en elk antwoord bevat de voortgang van de sessie onder upload. De sessie sluit pas wanneer elke pagina van 0 tot de laatste is aangekomen. Het sluiten verplaatst elk document in de gegevensbron dat geen enkele pagina van de sessie heeft genoemd en dat bestond voordat de sessie werd geopend, naar de prullenbak. Elke andere push naar de gegevensbron terwijl de sessie loopt, behoudt het document dat het noemt: een enkele push, een batch zonder sessievelden, een machtigingenupdate en een her-push van ongewijzigde inhoud. De prullenbak bewaart wat het sluiten ernaartoe heeft verplaatst voor 30 dagen; het opnieuw pushen van een document haalt het terug, net als het herstellen van de hele sessie (zie hieronder).

Een sessie die 24 uur lang geen pagina ontvangt, verloopt en wordt afgesloten zonder iets te verwijderen. Een geweigerde pagina krijgt een antwoord met 409 Conflict, schrijft niets weg, en de data.reason geeft aan waarom:

Om na een crash verder te gaan, lees de sessie uit met GET /documents/push/upload?tenantId=...&datasource=...&uploadId=... (scope index:status). De missingPageIndexes vermeldt de pagina's die nog moeten worden verstuurd.

Ongedaan maken van het sluiten van een sessieKopieer link naar deze kop

Als een sessie documenten heeft verwijderd die niet verwijderd hadden mogen worden, bijvoorbeeld omdat de lijst die het heeft verzonden onvolledig was, herstel ze dan in één aanroep:

curl https://nordvec.com/api/v1/documents/push/upload/restore \
  -H "Authorization: Bearer $NORDVEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "tenantId": "YOUR_WORKSPACE_ID", "datasource": "confluence-export", "uploadId": "nightly-2026-09-28" }'

De sleutel die de sessie heeft geopend, kan deze herstellen, en dat geldt ook voor een beheerder van de werkruimte die is ingelogd op Nordvec, voor een sessie die is geopend door elke sleutel. Elk document dat het sluiten naar de prullenbak heeft verplaatst, komt terug met de inhoud die het had, en het antwoord telt ze: restored zijn weer live, purged waren al definitief verwijderd door de prullenbak, en skipped zijn veranderd sinds het sluiten (opnieuw gepusht, of opnieuw verwijderd) en zijn ongewijzigd gelaten. Het tweemaal herstellen van een sessie antwoordt met de aantallen van de eerste herstelactie en "replayed": true, en zet elk hersteld document dat nog wacht om geïndexeerd te worden in de wachtrij, dus het herhalen van een herstelactie die niet heeft geantwoord, is veilig. Een sessie kan tot 35 dagen na het sluiten worden hersteld, en zolang de prullenbak nog een document bevat dat deze heeft verwijderd. Een geweigerd herstel wordt beantwoord met 409 Conflict en de data.reason:

Een push antwoordt zodra het document in de wachtrij staat. Vraag de voortgang op met GET /documents/push/status (scope index:status), gefilterd op gegevensbron of document-id. Een document gaat van queued via processing naar completed, of naar failed met een error.

Een push die een onbekende of gepauzeerde gegevensbron noemt, wordt beantwoord met 422 Unprocessable Content. Het bericht vermeldt de slug en linkt naar Instellingen werkruimte > Gegevensbronnen in jouw werkruimte, en de foutmelding data zegt waarom en wat te doen:

{
  "defined": true,
  "code": "UNPROCESSABLE_CONTENT",
  "status": 422,
  "message": "Datasource \"confluence-export\" is paused and accepts no documents. A workspace admin resumes it under Workspace settings > Datasources: https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources",
  "data": {
    "why": "The datasource \"confluence-export\" is paused",
    "fix": "Resume it at https://nordvec.com/w/YOUR_WORKSPACE_ID/workspace/settings?tab=datasources, then retry the push",
    "link": "https://nordvec.com/docs/guides/how-to/push-documents"
  }
}

Probeer deze niet automatisch opnieuw: ze slagen alleen nadat een beheerder de gegevensbron heeft aangemaakt of hervat.

POST /documents/push/delete (scope index:delete) verwijdert een gepusht document op basis van zijn datasource en id. Documenten die je niet meer pusht, worden niet vanzelf verwijderd: verwijder elk document dat je niet meer gebruikt, of stuur de volledige lijst van de gegevensbron als een uploadsessie, zoals hierboven beschreven.

• Pauzeren weigert elke verdere push naar de gegevensbron. De documenten blijven doorzoekbaar. Een push die al bezig was met schrijven wanneer je pauzeert, wordt voltooid.
• Hervatten accepteert pushes opnieuw.
• Verwijderen verwijdert de gegevensbron en elk document dat ernaar is gepusht, inclusief hun zoekindex. Jouw eigen systeem behoudt zijn kopie, dus het opnieuw pushen nadat je de gegevensbron opnieuw hebt aangemaakt, herstelt ze. Een verwijdering kan niet ongedaan worden gemaakt.

Als een andere beheerder de gegevensbron heeft gewijzigd nadat jouw lijst is geladen, wordt de actie geweigerd en laadt de lijst opnieuw, zodat je opnieuw beslist op basis van wat er nu staat. Elke aanmaak, pauze, hervatting en verwijdering wordt vastgelegd in het auditlogboek van de werkruimte.