Dokumente aus deinen eigenen Systemen pushen

Die Push-API indexiert Dokumente aus Systemen, für die Nordvec keinen Connector hat: einen internen Wiki-Export, ein Ticket-Archiv, eine Notizdatenbank. Du sendest den Text und legst fest, wer ihn lesen darf; Nordvec speichert ihn in der EU, indexiert ihn und macht ihn durchsuchbar und zitierbar wie jedes andere Dokument. Jedes gepushte Dokument landet in einer Datenquelle, einem benannten Container in deinem Arbeitsbereich, den ein Arbeitsbereich-Admin zuerst erstellt. Ein Push, der eine nicht existierende oder pausierte Datenquelle benennt, wird abgelehnt.

Öffne Arbeitsbereich-Einstellungen > Datenquellen und wähle Datenquelle erstellen. Arbeitsbereich-Admins und Eigentümer können das tun; in einem persönlichen Arbeitsbereich bist das du.

Der Slug confluence-export wird in den folgenden Beispielen verwendet.

Pushes authentifizieren sich mit einem API-Schlüssel der Klasse Indexing, der den index:write-Scope trägt. Füge index:status hinzu, um die Aufnahme zu verfolgen, und index:delete, um Dokumente zu entfernen oder eine gesamte Datenquelle zu ersetzen. Erstelle einen unter Arbeitsbereich-Einstellungen > API-Schlüssel. Der Rohschlüssel beginnt mit nv_eu_idx_ und wird nur einmal angezeigt. Siehe Authentication. Jede Anfrage enthält außerdem deine Arbeitsbereich-ID als tenantId, die ID in der Adresse deines Arbeitsbereichs in der App (/w/<workspace id>/...), und sie muss der Arbeitsbereich sein, zu dem der Schlüssel gehört.

/documents/push erstellt das Dokument oder aktualisiert es, wenn ein Dokument mit demselben id bereits in der Datenquelle existiert.

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 ist deine stabile ID für das Dokument innerhalb der Datenquelle. Wenn du denselben id erneut übermittelst, wird das Dokument aktualisiert. Unveränderter Inhalt wird anhand seines Hash-Werts erkannt und nicht zweimal indexiert.
• body.mimeType ist einer der Typen text/plain, text/markdown, text/html, application/pdf oder die Word-, Excel- und PowerPoint-Typen (.docx, .xlsx, .pptx). Binärinhalte werden base64-kodiert gesendet.
• sourceUrl wird zum "Zur Quelle springen"-Link bei jeder Zitierung des Dokuments. Lasse das Feld bei einer erneuten Übermittlung weg, um den gespeicherten Link beizubehalten, oder sende null, um ihn zu löschen.
• type legt den content_type des Dokuments fest, nach dem in der Suche und Filterliste gefiltert wird.

Der gesamte Anfragebody ist auf 1 MB begrenzt, sodass eine große Datei oder ein großer Batch mit 413 antwortet; teile sie auf.

permissions ist bei jedem Push erforderlich, sodass eine Freigabeentscheidung nie durch Weglassen eines Feldes getroffen wird. In einer für den Arbeitsbereich sichtbaren Datenquelle:

Um zu ändern, wer ein Dokument lesen darf, ohne dessen Inhalt erneut zu senden, verwende POST /documents/push/permissions. Damit ein bereits eingeschränktes Dokument für den gesamten Arbeitsbereich sichtbar wird, ist zusätzlich der index:acl-widen-Scope erforderlich. So kann eine routinemäßige Synchronisierung eine manuell gesetzte Einschränkung nicht unbemerkt aufheben.

/documents/push/bulk nimmt bis zu 100 Dokumente für eine Datenquelle pro Aufruf entgegen. Die Antwort zählt accepted und rejected und gibt ein Ergebnis pro Dokument zurück, sodass ein fehlerhaftes Dokument nicht den gesamten Batch fehlschlagen lässt. Die 1-MB-Grenze für den Body gilt pro Aufruf, daher teile große Uploads in mehrere Aufrufe unter derselben uploadId auf.

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": {} }
    ]
  }'

Wenn dein System alles auflisten kann, was eine Datenquelle enthalten soll, sende die vollständige Liste als eine Upload-Session, und die Dokumente, die sie nicht mehr enthält, werden in den Papierkorb verschoben, sobald die Session abgeschlossen ist. Sessions benötigen einen Indexing-API-Schlüssel, der sowohl index:delete als auch index:write enthält, da das Abschließen Dokumente entfernt; der Schlüssel, der eine Session eröffnet, ist der einzige, der sie fortsetzen kann.

1. Sende die erste Seite mit "isFirstPage": true. Das ist Seite 0.
2. Sende jede weitere Seite mit ihrem pageIndex (1, 2, ...), in beliebiger Reihenfolge. Eine Seite, die zweimal gesendet wird, zählt einmal, daher ist ein erneuter Versuch immer sicher.
3. Sende die letzte Seite mit "isLastPage": true und ihrem pageIndex. Eine Auflistung, die auf eine Seite passt, sendet isFirstPage und isLastPage zusammen. Die letzte Seite darf keine Dokumente enthalten.

Jede Seite verwendet denselben uploadId, und jede Antwort enthält den Fortschritt der Session unter upload. Die Session schließt erst, wenn jede Seite von 0 bis zur letzten eingetroffen ist. Durch das Schließen werden alle Dokumente in der Datenquelle, die keine Seite der Session benannt hat und die vor dem Öffnen der Session existierten, in den Papierkorb verschoben. Jeder andere Push in die Datenquelle während der Session läuft, behält das Dokument, das er benennt: ein einzelner Push, ein Batch ohne Session-Felder, eine Aktualisierung der Berechtigungen und ein erneutes Pushen unveränderten Inhalts gleichermaßen. Der Papierkorb behält, was das Schließen dorthin verschoben hat, für 30 Tage; ein erneutes Pushen eines Dokuments holt es zurück, und das Gleiche gilt für das Wiederherstellen der gesamten Session (siehe unten).

Eine Sitzung, die 24 Stunden lang keine Seite erhält, läuft ab und schließt ohne Entfernungen. Eine abgelehnte Seite wird mit 409 Conflict beantwortet, schreibt nichts und ihr data.reason erklärt den Grund:

Um nach einem Absturz fortzufahren, lies die Sitzung mit GET /documents/push/upload?tenantId=...&datasource=...&uploadId=... (Bereich index:status) aus. Ihr missingPageIndexes listet die noch zu sendenden Seiten auf.

Eine Session-Schließung rückgängig machenLink zu diesem Abschnitt kopieren

Wenn eine Session Dokumente entfernt hat, die nicht entfernt werden sollten, zum Beispiel weil die gesendete Liste unvollständig war, kannst du sie mit einem Aufruf wiederherstellen:

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

Der Schlüssel, der die Sitzung geöffnet hat, kann sie wiederherstellen, und das gilt auch für einen Arbeitsbereich-Admin, der bei Nordvec angemeldet ist, für eine von jedem Schlüssel geöffnete Sitzung. Jedes Dokument, das das Schließen in den Papierkorb verschoben hat, kommt mit dem Inhalt zurück, den es hatte, und die Antwort zählt sie: restored sind wieder live, purged waren bereits endgültig vom Papierkorb gelöscht, und skipped hatten sich seit dem Schließen geändert (erneut gepusht oder erneut entfernt) und blieben unverändert. Das Wiederherstellen einer Sitzung zweimal antwortet mit den Zählungen der ersten Wiederherstellung und "replayed": true und stellt jedes wiederhergestellte Dokument, das noch auf die Indexierung wartet, in die Warteschlange, sodass das Wiederholen einer fehlgeschlagenen Wiederherstellung sicher ist. Eine Sitzung kann bis zu 35 Tage nach ihrem Schließen wiederhergestellt werden, und so lange, wie der Papierkorb noch ein Dokument enthält, das sie entfernt hat. Eine abgelehnte Wiederherstellung wird mit 409 Conflict und ihrem data.reason beantwortet:

Ein Push antwortet, sobald das Dokument in die Warteschlange gestellt wurde. Frage den Fortschritt mit GET /documents/push/status (Scope index:status) ab, gefiltert nach Datenquelle oder Dokument-ID. Ein Dokument durchläuft die Stati von queued über processing zu completed oder zu failed mit einem error.

Ein Push, der eine unbekannte oder pausierte Datenquelle benennt, wird mit 422 Unprocessable Content beantwortet. Die Nachricht enthält den Slug und verlinkt auf Arbeitsbereich-Einstellungen > Datenquellen in deinem Arbeitsbereich, und das data des Fehlers erklärt, warum und was zu tun ist:

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

Wiederhole diese Anfragen nicht automatisch: Sie sind nur erfolgreich, nachdem ein Admin die Datenquelle erstellt oder fortgesetzt hat.

POST /documents/push/delete (Scope index:delete) entfernt ein hochgeladenes Dokument anhand seiner datasource und id. Dokumente, die du nicht mehr hochlädst, werden nicht automatisch gelöscht: Lösche jedes Dokument, das du nicht mehr benötigst, oder sende die vollständige Auflistung der Datenquelle als Upload-Session, wie oben beschrieben.

• Pausieren lehnt jeden weiteren Push in die Datenquelle ab. Ihre Dokumente bleiben durchsuchbar. Ein Push, der bereits geschrieben wird, wenn du pausierst, wird abgeschlossen.
• Fortsetzen akzeptiert Pushes wieder.
• Löschen entfernt die Datenquelle und jedes in sie gepushte Dokument, einschließlich ihres Suchindex. Dein eigenes System behält seine Kopie, sodass ein erneutes Pushen nach dem Neuerstellen der Datenquelle sie wiederherstellt. Ein Löschen kann nicht rückgängig gemacht werden.

Wenn ein anderer Admin die Datenquelle geändert hat, nachdem deine Liste geladen wurde, wird die Aktion abgelehnt und die Liste neu geladen, sodass du erneut gegen den aktuellen Stand entscheidest. Jedes Erstellen, Pausieren, Fortsetzen und Löschen wird im Arbeitsbereich-Audit-Log protokolliert.