Poussez des documents depuis vos propres systèmes

L'API push indexe des documents provenant de systèmes pour lesquels Nordvec ne dispose pas de connecteur : une export de wiki interne, une archive de tickets, une base de données de notes. Vous envoyez le texte et les personnes autorisées à le lire ; Nordvec le stocke dans l'UE, l'indexe et le rend consultable et citable comme tout autre document. Chaque document poussé atterrit dans une source de données, un conteneur nommé dans votre espace de travail qu'un administrateur de l'espace de travail crée en premier. Une poussée qui nomme une source de données inexistante ou en pause est refusée.

Ouvrez Paramètres de l'espace de travail > Sources de données et choisissez Créer une source de données. Les administrateurs et les propriétaires de l'espace de travail peuvent le faire ; dans un espace de travail personnel, c'est vous.

Le slug confluence-export est utilisé dans les exemples ci-dessous.

Les requêtes de push s'authentifient avec une clé API de la classe Indexation qui porte le scope index:write. Ajoutez index:status pour suivre l'ingestion et index:delete pour supprimer des documents ou remplacer une source de données entière. Créez-en une sous Paramètres de l'espace de travail > Clés API ; la clé brute commence par nv_eu_idx_ et n'est affichée qu'une fois. Voir Authentification. Chaque requête nomme également l'identifiant de votre espace de travail sous tenantId, l'identifiant présent dans l'adresse de votre espace de travail dans l'application (/w/<workspace id>/...), et il doit s'agir de l'espace de travail auquel la clé appartient.

/documents/push crée le document, ou le met à jour lorsqu'un document avec le même id existe déjà dans la source de données.

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 est votre identifiant stable pour le document au sein de la source de données. Pousser le même id à nouveau le met à jour ; un contenu inchangé est reconnu par son hachage et n'est pas indexé deux fois.
• body.mimeType est l'un des types suivants : text/plain, text/markdown, text/html, application/pdf, ou les types Word, Excel et PowerPoint (.docx, .xlsx, .pptx). Le contenu binaire est envoyé encodé en base64.
• sourceUrl devient le lien « sauter à la source » sur chaque citation du document. Omettez-le lors d'une nouvelle poussée pour conserver celui déjà stocké, ou envoyez null pour le supprimer.
• type définit le content_type du document, sur lequel la recherche et les filtres de liste s'appuient.

Le corps de la requête entier est limité à 1 Mo, donc un fichier volumineux ou un grand lot répond 413 ; divisez-le.

permissions est requis à chaque poussée, afin qu'une décision de partage ne soit jamais prise en omettant un champ. Dans une source de données visible par l'espace de travail :

Pour modifier qui peut lire un document sans renvoyer son contenu, utilisez POST /documents/push/permissions. Rendre un document déjà restreint visible par tout l'espace de travail nécessite en plus le scope index:acl-widen, afin qu'une synchronisation de routine ne puisse pas annuler discrètement une restriction définie manuellement.

/documents/push/bulk accepte jusqu'à 100 documents pour une seule source de données par appel. La réponse compte accepted et rejected et donne un résultat par document, de sorte qu'un document défectueux ne fasse pas échouer le lot. La limite de 1 Mo pour le corps s'applique par appel, divisez donc les gros téléchargements en plusieurs appels sous le même 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": {} }
    ]
  }'

Lorsque votre système peut lister tout ce qu'une source de données doit contenir, envoyez la liste complète sous la forme d'une session de téléchargement, et les documents qu'elle ne contient plus sont déplacés vers la corbeille lorsque la session se ferme. Les sessions nécessitent une clé API d'indexation portant index:delete ainsi que index:write, car la fermeture supprime des documents ; la clé qui ouvre une session est la seule qui puisse la poursuivre.

1. Envoyez la première page avec "isFirstPage": true. Il s'agit de la page 0.
2. Envoyez chaque page suivante avec son pageIndex (1, 2, ...), dans n'importe quel ordre. Une page envoyée deux fois n'est comptée qu'une fois, donc une nouvelle tentative est toujours sûre.
3. Envoyez la dernière page avec "isLastPage": true et son pageIndex. Une liste qui tient en une seule page envoie isFirstPage et isLastPage ensemble. La dernière page peut ne contenir aucun document.

Chaque page utilise le même uploadId, et chaque réponse contient la progression de la session sous upload. La session ne se ferme que lorsque chaque page de 0 à la dernière est arrivée. La fermer déplace vers la corbeille chaque document de la source de données qui n'a pas été nommé par une page de la session et qui existait avant l'ouverture de celle-ci. Toute autre poussée vers la source de données pendant l'exécution de la session conserve le document qu'elle nomme : une poussée unique, un lot sans champs de session, une mise à jour des permissions, et une nouvelle poussée de contenu inchangé de la même manière. La corbeille conserve ce que la fermeture y a déplacé pendant 30 jours ; pousser à nouveau un document le ramène, tout comme la restauration de la session entière (voir ci-dessous).

Une session qui ne reçoit aucune page pendant 24 heures expire et se termine sans rien supprimer. Une page refusée reçoit une réponse 409 Conflict, n'écrit rien, et son data.reason explique pourquoi :

Pour reprendre après un plantage, lisez la session avec GET /documents/push/upload?tenantId=...&datasource=...&uploadId=... (portée index:status). Son missingPageIndexes liste les pages encore à envoyer.

Annuler la fermeture d'une sessionCopier le lien vers cette section

Si une session a supprimé des documents qu'elle n'aurait pas dû, par exemple parce que la liste envoyée était incomplète, restaurez-les en un seul appel :

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" }'

La clé qui a ouvert la session peut la restaurer, et un administrateur d'espace de travail connecté à Nordvec peut le faire pour une session ouverte par n'importe quelle clé. Chaque document que la fermeture a déplacé dans la corbeille revient avec son contenu d'origine, et la réponse en compte le nombre : restored sont de nouveau actifs, purged avaient déjà été définitivement supprimés par la corbeille, et skipped avaient changé depuis la fermeture (repoussés ou supprimés à nouveau) et ont été laissés tels quels. Restaurer une session deux fois répond avec les comptes de la première restauration et "replayed": true, et met en file d'attente tout document restauré toujours en attente d'indexation. Répéter une restauration qui n'a pas abouti est donc sans risque. Une session peut être restaurée jusqu'à 35 jours après sa fermeture, et tant que la corbeille contient encore un document qu'elle a supprimé. Une restauration refusée est répondue avec 409 Conflict et son data.reason :

Une poussée répond dès que le document est mis en file d'attente. Demandez sa progression avec GET /documents/push/status (scope index:status), filtrée par source de données ou identifiant de document. Un document passe de queued à processing, puis à completed, ou à failed avec un error.

Une poussée qui nomme une source de données inconnue ou en pause reçoit une réponse 422 Unprocessable Content. Le message nomme le slug et contient un lien vers Paramètres de l'espace de travail > Sources de données dans votre espace de travail, et le data de l'erreur indique pourquoi et ce qu'il faut faire :

{
  "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"
  }
}

Ne réessayez pas automatiquement ces poussées : elles ne réussissent qu'après qu'un administrateur a créé ou repris la source de données.

POST /documents/push/delete (portée index:delete) supprime un document poussé par son datasource et son id. Les documents que vous cessez de pousser ne sont pas supprimés automatiquement : supprimez chacun de ceux que vous retirez, ou envoyez la liste complète de la source de données en tant que session de téléversement, comme décrit ci-dessus.

• Mettre en pause refuse toute poussée ultérieure dans la source de données. Ses documents restent consultables. Une poussée déjà en cours d'écriture au moment où vous mettez en pause se termine.
• Reprendre accepte à nouveau les poussées.
• Supprimer retire la source de données et tous les documents qui y ont été poussés, ainsi que leur index de recherche. Votre propre système conserve sa copie, donc pousser à nouveau après avoir recréé la source de données les restaure. Une suppression ne peut pas être annulée.

Si un autre administrateur a modifié la source de données après le chargement de votre liste, l'action est refusée et la liste se recharge, afin que vous puissiez décider à nouveau en fonction de l'état actuel. Chaque création, pause, reprise et suppression est enregistrée dans le journal d'audit de l'espace de travail.