Skicka dokument från dina egna system

Med push-API:t indexerar du dokument från system som Nordvec inte har en anslutning för: en export från ett internt wiki, ett ärendearkiv, en databas med anteckningar. Du skickar texten och vem som får läsa den; Nordvec lagrar den i EU, indexerar den och gör den sökbar och citerbar precis som alla andra dokument. Varje pushat dokument hamnar i en datakälla, en namngiven behållare i din arbetsyta som en administratör för arbetsytan först skapar. En push som namnger en datakälla som inte finns, eller en som är pausad, nekas.

Öppna Inställningar för arbetsyta > Datakällor och välj Skapa datakälla. Administratörer och ägare för arbetsytan kan göra detta; i en personlig arbetsyta är det du.

Sluggen confluence-export används i exemplen nedan.

Pushar autentiseras med en API-nyckel av klassen Indexing som har scopet index:write; lägg till index:status för att spåra inmatning och index:delete för att ta bort dokument eller ersätta en hel datakälla. Skapa en under Inställningar för arbetsyta > API-nycklar; den råa nyckeln börjar med nv_eu_idx_ och visas en gång. Se Autentisering. Varje begäran namnger även ditt arbetsyta-ID som tenantId, det ID som finns i din arbetsytas adress i appen (/w/<workspace id>/...), och det måste vara den arbetsyta som nyckeln tillhör.

/documents/push skapar dokumentet, eller uppdaterar det om ett dokument med samma id redan finns i datakällan.

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 är ditt stabila id för dokumentet inom datakällan. Om du pushar samma id igen uppdateras det; oförändrat innehåll känns igen på sin hash och indexeras inte två gånger.
• body.mimeType är ett av text/plain, text/markdown, text/html, application/pdf, eller Word-, Excel- och PowerPoint-typerna (.docx, .xlsx, .pptx). Binärt innehåll skickas base64-kodat.
• sourceUrl blir "hoppa till källa"-länken på varje citering av dokumentet. Utelämna det vid en ny push för att behålla den lagrade länken, eller skicka null för att rensa den.
• type anger dokumentets content_type, som sökning och listor filtrerar på.

Hela förfrågningskroppen är begränsad till 1 MB, så en stor fil eller ett stort parti svarar med 413; dela upp det.

permissions är obligatoriskt vid varje push, så ett delningsbeslut fattas aldrig genom att utelämna ett fält. I en datakälla som är synlig för arbetsytan:

För att ändra vem som får läsa ett dokument utan att skicka innehållet igen, använd POST /documents/push/permissions. Att göra ett redan begränsat dokument synligt för hela arbetsytan kräver dessutom scopet index:acl-widen, så att en rutinmässig synkronisering inte tyst kan ångra en begränsning som någon har ställt in manuellt.

/documents/push/bulk tar emot upp till 100 dokument för en datakälla per anrop. Svaret räknar accepted och rejected och ger ett resultat per dokument, så ett felaktigt dokument inte gör att hela batchen misslyckas. Gränsen på 1 MB för kroppen gäller per anrop, så dela upp stora uppladdningar i flera anrop under samma 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": {} }
    ]
  }'

När ditt system kan lista allt som en datakälla ska innehålla, skicka hela listan som en uppladdningssession, och dokumenten som inte längre finns med flyttas till papperskorgen när sessionen avslutas. Sessioner kräver en indexerings-API-nyckel som har både index:delete och index:write, eftersom avslutningen tar bort dokument; nyckeln som öppnar en session är den enda som kan fortsätta den.

1. Skicka första sidan med "isFirstPage": true. Det är sida 0.
2. Skicka varje ytterligare sida med dess pageIndex (1, 2, ...), i valfri ordning. En sida som skickas två gånger räknas en gång, så ett nytt försök är alltid säkert.
3. Skicka sista sidan med "isLastPage": true och dess pageIndex. En lista som ryms på en sida skickar isFirstPage och isLastPage tillsammans. Den sista sidan får vara utan dokument.

Varje sida använder samma uploadId, och varje svar innehåller sessionens framsteg under upload. Sessionen avslutas först när alla sidor från 0 till den sista har kommit in. När den avslutas flyttas varje dokument i datakällan som ingen sida i sessionen nämnde och som fanns innan sessionen öppnades till papperskorgen. Alla andra pushar till datakällan medan sessionen pågår behåller dokumentet de nämner: en enskild push, en batch utan sessionsfält, en behörighetsuppdatering och en ompush av oförändrat innehåll likaså. Papperskorgen behåller det som flyttades dit i 30 dagar; att pusha ett dokument igen återställer det, och det gör även att återställa hela sessionen (se nedan).

En session som inte tar emot någon sida på 24 timmar upphör och avslutas utan att ta bort något. Ett nekad sida besvaras med 409 Conflict, skriver ingenting, och dess data.reason förklarar varför:

För att återuppta efter ett avbrott, läs sessionen med GET /documents/push/upload?tenantId=...&datasource=...&uploadId=... (scope index:status). Dess missingPageIndexes listar de sidor som fortfarande måste skickas.

Ångra en sessions avslutningKopiera länk till detta avsnitt

Om en session har tagit bort dokument som den inte borde ha, till exempel för att listan den skickade var ofullständig, kan du återställa dem med ett anrop:

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

Nyckeln som öppnade sessionen kan återställa den, och detsamma gäller en arbetsyteadministratör inloggad på Nordvec, för en session som öppnats med vilken nyckel som helst. Alla dokument som stängningen flyttade till papperskorgen kommer tillbaka med sitt innehåll intakt, och svaret räknar dem: restored är åter aktiva, purged hade redan raderats permanent från papperskorgen, och skipped hade ändrats sedan stängningen (skickats igen eller tagits bort igen) och lämnades som de är. Om du återställer en session två gånger svarar systemet med första återställningens antal och "replayed": true, och lägger eventuella återställda dokument som fortfarande väntar på indexering i kö. Det är därför säkert att upprepa en återställning som inte gav något svar. En session kan återställas upp till 35 dagar efter att den stängdes, och så länge papperskorgen fortfarande innehåller något dokument som den tog bort. Ett nekad återställning besvaras med 409 Conflict och dess data.reason:

En push svarar så snart dokumentet har lagts i kö. Fråga efter dess framsteg med GET /documents/push/status (scope index:status), filtrerat efter datakälla eller dokument-id. Ett dokument går från queued via processing till completed, eller till failed med en error.

En push som namnger en okänd eller pausad datakälla besvaras med 422 Unprocessable Content. Meddelandet namnger sluggen och länkar till Inställningar för arbetsyta > Datakällor i din arbetsyta, och felets data förklarar varför och vad du ska göra:

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

Försök inte igen automatiskt: de lyckas först efter att en admin har skapat eller återupptagit datakällan.

POST /documents/push/delete (scope index:delete) tar bort ett uppladdat dokument med dess datasource och id. Dokument som du slutar skicka tas inte bort automatiskt: radera varje dokument du avvecklar, eller skicka datakällans fullständiga lista som en uppladdningssession, beskrivet ovan.

• Pausa nekar varje ytterligare push till datakällan. Dess dokument förblir sökbara. En push som redan pågår när du pausar slutförs.
• Återuppta accepterar pushes igen.
• Ta bort raderar datakällan och alla dokument som pushats till den, inklusive deras sökindex. Ditt eget system behåller sin kopia, så om du pushar igen efter att du återskapar datakällan återställs de. Ett borttag kan inte ångras.

Om en annan admin har ändrat datakällan efter att din lista laddades, nekas åtgärden och listan laddas om, så att du fattar beslut utifrån det aktuella läget. Varje skapande, pausning, återupptagande och borttagning loggas i arbetsytans granskningslogg.