# Context pack: Carica documenti dai tuoi sistemi
Source: https://nordvec.com/it/docs/guides/how-to/push-documents
Pack: https://nordvec.com/it/docs/packs/how-to/push-documents
This pack bundles one Nordvec guide with the guides it builds on and the guides it links to, in reading order, so an assistant reading it meets no reference it cannot follow.
## Contents
1. [Autenticazione](https://nordvec.com/it/docs/guides/authentication) (builds on)
2. [Errori e limiti di frequenza](https://nordvec.com/it/docs/guides/errors-and-rate-limits) (builds on)
3. [Carica documenti dai tuoi sistemi](https://nordvec.com/it/docs/guides/how-to/push-documents) (this guide)
4. [Filtra e affina la ricerca](https://nordvec.com/it/docs/guides/how-to/filter-search) (linked from this guide)
5. [Elenca e recupera i documenti](https://nordvec.com/it/docs/guides/how-to/list-documents) (linked from this guide)
---
# Autenticazione
Source: https://nordvec.com/it/docs/guides/authentication
Autentica le richieste API con una chiave API dell'area di lavoro inviata come bearer token e scegli la classe della chiave e gli ambiti di cui un lavoro ha bisogno.
Una chiamata al programma utilizza l'API di Nordvec con una **chiave API**, inviata come token bearer nell'intestazione `Authorization`.
```bash
curl https://nordvec.com/api/v1/documents/list \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
Non tutti gli endpoint richiedono una chiave. Le conversazioni, i webhook e la gestione delle chiavi appartengono a una persona autenticata e rispondono solo a una sessione; la [riferimento API](/docs/api) indica per ogni operazione le credenziali che accetta.
## Classi di chiavi [#classi-di-chiavi]
Una chiave appartiene a una di due classi, e il suo prefisso ne indica la classe:
| Classe | Prefisso | Per |
| -------- | ------------- | ---------------------------------------------------------------------------------------------- |
| Client | `nv_eu_live_` | Lettura: ricerca, elencazione e recupero documenti, quota, audit trail |
| Indexing | `nv_eu_idx_` | Scrittura: invio, eliminazione e modifica dei permessi dei documenti, verifica dell'ingestione |
## Ambiti [#ambiti]
Una chiave possiede uno o più ambiti, e un'operazione risponde `403` a una chiave che non ha l'ambito necessario. Una chiave può avere solo ambiti della propria classe.
| Ambito | Classe | Consente |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `search:read` | Client | Ricerca, elencazione, recupero e recupero batch di documenti |
| `quota:read` | Client | Quota di embedding e analisi dell'utilizzo |
| `audit:read` | Client | Ricerca nell'audit trail dell'area di lavoro e lettura del suo catalogo eventi |
| `index:write` | Indexing | Invio e invio bulk di documenti, aggiornamento dei loro permessi |
| `index:delete` | Indexing | Eliminazione di documenti inviati |
| `index:status` | Indexing | Stato dell'invio e salute dell'ingestione |
| `index:acl-widen` | Indexing | Rendere visibile a tutta l'area di lavoro un documento già limitato. Una chiave con questo ambito deve avere una scadenza |
Assegna a ogni chiave il minor numero di ambiti necessari per il suo compito, in modo che una chiave compromessa possa fare il meno possibile.
## Creazione di una chiave [#creazione-di-una-chiave]
Crea una chiave in **Impostazioni > Chiavi API**. Per crearne una è necessario il ruolo di **proprietario** o **amministratore** dell'area di lavoro; in un'area di lavoro personale, sei tu. La **chiave grezza viene restituita una sola volta** e non è più recuperabile in seguito, quindi copiala subito nel tuo archivio segreto.
Una chiave appartiene all'area di lavoro, non alla persona che l'ha creata. Legge ciò che l'area di lavoro condivide: i documenti che una persona ha collegato ma non condiviso rimangono visibili solo a quella persona, e nessuna chiave può vederli.
Una chiave può anche avere una scadenza (da 1 a 3650 giorni) e un elenco di indirizzi IP consentiti fino a 50 indirizzi o intervalli CIDR.
## Rotazione e revoca [#rotazione-e-revoca]
Tratta una chiave API come una password. Se una chiave viene compromessa, ruotala o revocala immediatamente.
* **Ruota** sostituisce in loco la credenziale di una chiave. La credenziale precedente continua a funzionare per una finestra di tolleranza che scegli: nessuna, 15 minuti, 1 ora, 6 ore o 24 ore (impostazione predefinita), in modo da poter distribuire la nuova credenziale ai tuoi servizi senza tempi di inattività.
* **Revoca** disabilita immediatamente una chiave; non può più autenticarsi.
Entrambe le azioni richiedono una sessione autenticata (non sono esse stesse operazioni con chiave API), quindi una chiave compromessa non può essere utilizzata per ruotare se stessa.
## Buone pratiche [#buone-pratiche]
* Memorizza le chiavi in un gestore di segreti o in una variabile d'ambiente, mai nel codice sorgente.
* Usa una chiave separata per ogni servizio o ambiente, in modo da poter revocare in modo mirato.
* Imposta una scadenza per le chiavi utilizzate in CI e script.
---
# Errori e limiti di frequenza
Source: https://nordvec.com/it/docs/guides/errors-and-rate-limits
La singola busta di errore che ogni richiesta fallita restituisce, le intestazioni del limite di frequenza e come ritentare una scrittura in modo sicuro.
Ogni endpoint fallisce allo stesso modo, quindi un client gestisce errori, limiti di frequenza e tentativi una volta sola e riutilizza quel codice ovunque, incluso su [MCP](/docs/guides/mcp).
## La busta di errore [#la-busta-di-errore]
Ogni risposta non-2xx è un oggetto JSON:
```json
{
"defined": false,
"code": "TOO_MANY_REQUESTS",
"message": "Too many requests",
"data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```
* `code` è l'errore a livello HTTP, ad esempio `UNAUTHORIZED`, `FORBIDDEN`,
`NOT_FOUND`, `BAD_REQUEST` o `TOO_MANY_REQUESTS`.
* `data.reason`, quando presente, è un motivo più preciso leggibile dalla macchina come
`auth.key_not_found` o `rate_limit.exceeded`. Fai branching su questo piuttosto che su
`message`, che è per le persone e può cambiare.
* `defined` è `true` quando l'operazione elenca quell'errore nella
[riferimento API](/docs/api), e `false` per errori che qualsiasi richiesta può incontrare
(autenticazione, limiti di frequenza, una rotta sconosciuta).
* Un fallimento di validazione risponde `BAD_REQUEST` con i problemi in
`data.formErrors` e `data.fieldErrors`.
Ogni risposta include anche un `X-Request-ID`. Citalo quando contatti
l'assistenza, così possiamo trovare quella richiesta esatta.
## Stati comuni [#stati-comuni]
| Stato | Codice | Cosa fare |
| ----- | ----------------------- | ---------------------------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Correggi la richiesta; `data.fieldErrors` indica i campi |
| `401` | `UNAUTHORIZED` | Invia una chiave o sessione valida |
| `403` | `FORBIDDEN` | La chiave non ha lo scope o il ruolo richiesto dall'operazione |
| `404` | `NOT_FOUND` | La risorsa non esiste, oppure non hai il permesso di vederla |
| `409` | `CONFLICT` | Una scrittura duplicata è ancora in corso; riprova tra poco |
| `413` | `PAYLOAD_TOO_LARGE` | Il corpo della richiesta supera 1 MB; suddividi un invio bulk in batch più piccoli |
| `422` | `UNPROCESSABLE_CONTENT` | La richiesta è ben formata ma non può essere applicata |
| `429` | `TOO_MANY_REQUESTS` | Attendi `Retry-After`, poi riprova |
## Limiti di frequenza [#limiti-di-frequenza]
Ogni risposta indica il limite contro cui è stata conteggiata, in due forme:
* le intestazioni `X-RateLimit-*`;
* i campi strutturati IETF `RateLimit` (stato attuale: `r` sono le richieste
rimanenti, `t` i secondi fino al reset della finestra) e `RateLimit-Policy`
(la quota: `q` è il limite, `w` la finestra in secondi).
Una `429` include anche `Retry-After` in secondi e `data.retryAfterMs`. Attendi almeno quel tempo
prima della prossima richiesta; riprovare prima viene conteggiato e rifiutato di nuovo.
## Ripetizione sicura delle scritture [#ripetizione-sicura-delle-scritture]
Un'operazione di scrittura che elenca un'intestazione `Idempotency-Key` nella
[riferimento API](/docs/api) può essere ripetuta senza eseguire il lavoro due volte. Invia
una chiave per ogni scrittura logica e ripeti la stessa chiave in ogni tentativo:
* la stessa chiave con lo stesso corpo entro 24 ore riproduce la risposta memorizzata;
* la stessa chiave con un corpo diverso viene rifiutata con `422`;
* un duplicato che arriva mentre il primo è ancora in esecuzione riceve `409`.
Un'operazione senza l'intestazione non è idempotente, quindi ripetila solo quando sai che il primo tentativo non è andato a buon fine.
---
# Carica documenti dai tuoi sistemi
Source: https://nordvec.com/it/docs/guides/how-to/push-documents
Crea un'origine dati, carica i documenti al suo interno con una chiave API di indicizzazione, scegli chi può leggerli e mettila in pausa o eliminala quando la fonte cambia.
L'API push indicizza documenti provenienti da sistemi per cui Nordvec non dispone di un connettore: un export di una wiki interna, un archivio di ticket, un database di note. Tu invii il testo e chi può leggerlo; Nordvec lo memorizza nell'UE, lo indicizza e lo rende ricercabile e citabile come qualsiasi altro documento. Ogni documento inviato finisce in un'**origine dati**, un contenitore nominato nella tua area di lavoro che un amministratore dell'area di lavoro crea per primo. Un push che nomina un'origine dati inesistente o in pausa viene rifiutato.
## Crea un'origine dati [#crea-unorigine-dati]
Apri **Impostazioni area di lavoro > Origini dati** e scegli **Crea origine dati**. Possono farlo gli amministratori e i proprietari dell'area di lavoro; in un'area di lavoro personale, sei tu.
| Campo | Note |
| ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nome | Ciò che le persone vedono nell'elenco delle impostazioni. Fino a 200 caratteri. |
| Slug | Ciò che ogni push nomina. Lettere minuscole, cifre, `-` e `_`, inizia con una lettera o una cifra, fino a 200 caratteri. Non può essere modificato in seguito. |
Lo slug `confluence-export` viene utilizzato negli esempi seguenti.
## Crea una chiave API di indicizzazione [#crea-una-chiave-api-di-indicizzazione]
I push si autenticano con una chiave API della classe **Indexing** che include l'ambito `index:write`; aggiungi `index:status` per tracciare l'indicizzazione e `index:delete` per rimuovere documenti o sostituire un'intera origine dati. Creane una sotto **Impostazioni area di lavoro > Chiavi API**; la chiave grezza inizia con `nv_eu_idx_` ed è mostrata una sola volta. Vedi [Authentication](/docs/guides/authentication). Ogni richiesta nomina anche il tuo id dell'area di lavoro come `tenantId`, l'id nell'indirizzo della tua area di lavoro nell'app (`/w//...`), e deve essere l'area di lavoro a cui la chiave appartiene.
## Invia un documento [#invia-un-documento]
`/documents/push` crea il documento o lo aggiorna se un documento con lo stesso `id` esiste già nell'origine dati.
```bash
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"
}
}'
```
```json
{ "documentId": "page-4711", "status": "queued", "updated": false }
```
* `id` è il tuo id stabile per il documento all'interno dell'origine dati. Inviare nuovamente lo stesso `id` lo aggiorna; il contenuto invariato è riconosciuto dal suo hash e non viene indicizzato due volte.
* `body.mimeType` è uno tra `text/plain`, `text/markdown`, `text/html`, `application/pdf`, o i tipi Word, Excel e PowerPoint (`.docx`, `.xlsx`, `.pptx`). Il contenuto binario è inviato codificato in base64.
* `sourceUrl` diventa il link "vai alla fonte" su ogni citazione del documento. Omettilo in un re-push per mantenere quello memorizzato, o invia `null` per cancellarlo.
* `type` imposta il `content_type` del documento, su cui la ricerca e l'elenco filtrano.
L'intero corpo della richiesta è limitato a 1 MB, quindi un file grande o un batch corposo risponde con `413`; suddividilo.
## Scegli chi può leggerlo [#scegli-chi-può-leggerlo]
`permissions` è obbligatorio in ogni push, quindi una decisione di condivisione non viene mai presa omettendo un campo. In un'origine dati visibile all'area di lavoro:
| `permissions` | Chi può leggere il documento |
| ----------------------------------------- | ---------------------------------------------------------------------- |
| `{}` | Ogni membro dell'area di lavoro |
| `{ "allowedUsers": ["ana@example.com"] }` | Solo le persone elencate |
| `{ "allowedGroups": ["GROUP_ID"] }` | Membri di quei gruppi dell'area di lavoro, inclusi i gruppi nidificati |
| `{ "allowAllTenantMembers": false }` | Rifiutato: un documento che nessuno può leggere è una cancellazione |
Per cambiare chi può leggere un documento senza inviare nuovamente il suo contenuto, usa `POST /documents/push/permissions`. Rendere un documento già ristretto visibile a tutta l'area di lavoro richiede inoltre l'ambito `index:acl-widen`, quindi una sincronizzazione di routine non può annullare silenziosamente una restrizione impostata manualmente.
## Invia in batch [#invia-in-batch]
`/documents/push/bulk` accetta fino a 100 documenti per un'origine dati per chiamata. La risposta conta `accepted` e `rejected` e fornisce un risultato per documento, quindi un documento errato non fa fallire il batch. Il limite di 1 MB per il corpo si applica per chiamata, quindi suddividi i caricamenti di grandi dimensioni in più chiamate sotto lo stesso `uploadId`.
```bash
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": {} }
]
}'
```
## Sostituisci un'intera origine dati [#sostituisci-unintera-origine-dati]
Quando il tuo sistema può elencare tutto ciò che un'origine dati dovrebbe contenere, invia l'intero elenco come una **sessione di caricamento**, e i documenti che non contiene più vengono spostati nel cestino quando la sessione si chiude. Le sessioni richiedono una chiave API di indicizzazione che includa `index:delete` oltre a `index:write`, perché la chiusura rimuove i documenti; la chiave che ne apre una è l'unica che può continuarla.
1. Invia la prima pagina con `"isFirstPage": true`. È la pagina `0`.
2. Invia ogni pagina successiva con il suo `pageIndex` (`1`, `2`, ...), in qualsiasi ordine.
Una pagina inviata due volte viene conteggiata una sola volta, quindi un nuovo tentativo è sempre sicuro.
3. Invia l'ultima pagina con `"isLastPage": true` e il suo `pageIndex`. Un elenco
che rientra in una sola pagina invia `isFirstPage` e `isLastPage` insieme. L'ultima
pagina può non contenere documenti.
Ogni pagina utilizza lo stesso `uploadId`, e ogni risposta riporta lo stato di avanzamento della sessione in `upload`. La sessione si chiude solo quando ogni pagina da `0` all'ultima è arrivata. Chiuderla sposta nel cestino ogni documento nell'origine dati che nessuna pagina della sessione ha nominato e che esisteva prima dell'apertura della sessione. Qualsiasi altro push all'origine dati mentre la sessione è in corso mantiene il documento che nomina: un singolo push, un batch senza campi di sessione, un aggiornamento dei permessi e un re-push di contenuto invariato allo stesso modo. Il cestino conserva ciò che la chiusura vi ha spostato per 30 giorni; inviare nuovamente un documento lo ripristina, così come il ripristino dell'intera sessione (vedi sotto).
Una sessione che non riceve pagine per 24 ore scade e si chiude senza rimuovere nulla. Una pagina rifiutata riceve una risposta con `409 Conflict`, non scrive nulla, e il suo `data.reason` spiega il motivo:
| `reason` | Cosa fare |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upload_incomplete` | Invia le pagine elencate in `missingPageIndexes`, poi invia di nuovo l'ultima pagina |
| `deletion_confirmation_required` | La chiusura sposterebbe nel cestino più del 20% dell'origine dati. Se è corretto, invia di nuovo l'ultima pagina con `"confirmDeletions"` impostato su `wouldTombstone` |
| `deletion_confirmation_too_large` | `confirmDeletions` è maggiore del numero di documenti che l'origine dati conteneva quando la sessione è stata aperta. Invia il conteggio che prevedi di rimuovere |
| `upload_in_progress` | Una sessione è aperta su questa origine dati. Se è la chiave della tua sessione, completala, attendi che scada o ricomincia con `"forceRestartUpload": true` sulla prima pagina. Se un'altra chiave l'ha aperta, `forceRestartUpload` la sostituisce solo una volta che non ha ricevuto pagine per un'ora, dal momento indicato in `restartableAt` |
| `upload_expired`, `upload_missing`, `upload_restarted` | La sessione è terminata; inizia una nuova sessione con un nuovo `uploadId` |
| `upload_closed`, `upload_id_reused` | La `uploadId` è esaurita; usa una nuova |
| `page_index_required` | La tua chiave ha una sessione aperta su questa origine dati; invia `pageIndex` con la pagina |
Per riprendere dopo un crash, leggi la sessione con `GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (ambito `index:status`). Il suo `missingPageIndexes` elenca le pagine ancora da inviare.
### Annulla la chiusura di una sessione [#annulla-la-chiusura-di-una-sessione]
Se una sessione ha rimosso documenti che non avrebbe dovuto, ad esempio perché l'elenco inviato era incompleto, ripristinali con una singola chiamata:
```bash
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 chiave che ha aperto la sessione può ripristinarla, così come può farlo un amministratore dell'area di lavoro connesso a Nordvec, per una sessione aperta da qualsiasi chiave. Ogni documento che la chiusura ha spostato nel cestino torna con il contenuto che aveva, e la risposta ne conta il numero: `restored` sono di nuovo attivi, `purged` erano già stati eliminati definitivamente dal cestino, e `skipped` erano cambiati dalla chiusura (ri-pubblicati o rimossi di nuovo) e sono stati lasciati così com'erano. Ripristinare una sessione due volte risponde con i conteggi del primo ripristino e `"replayed": true`, e mette in coda ogni documento ripristinato ancora in attesa di essere indicizzato, quindi ripetere un ripristino che non ha risposto è sicuro. Una sessione può essere ripristinata entro 35 giorni dalla sua chiusura, e per tutto il tempo in cui il cestino contiene ancora almeno un documento che ha rimosso. Un ripristino rifiutato viene risposto con `409 Conflict` e il suo `data.reason`:
| `reason` | Cosa significa |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `upload_not_closed` | La sessione non è mai stata chiusa, quindi non ha rimosso nulla |
| `upload_in_progress` | Una sessione è aperta sull'origine dati. Ripristina una volta che si è chiusa o è scaduta |
| `restore_purged` | Sono passati più di 30 giorni e il cestino ha eliminato tutti i documenti. Inviarli nuovamente |
| `workspace_not_entitled` | Il piano dell'area di lavoro non consente attualmente il ripristino dal cestino |
| `corpus_cap_exceeded` | Riportare i documenti supererebbe il limite di documenti dell'area di lavoro, quindi nessuno è stato ripristinato. `data.wouldRestore` è quanti ne servono e `data.headroom` quanti ne stanno. Libera spazio, poi ripristina di nuovo |
## Traccia l'acquisizione [#traccia-lacquisizione]
Un push risponde non appena il documento viene messo in coda. Chiedi il suo stato di avanzamento con `GET /documents/push/status` (ambito `index:status`), filtrato per origine dati o id del documento. Un documento passa da `queued` attraverso `processing` a `completed`, o a `failed` con un `error`.
## Quando un push viene rifiutato [#quando-un-push-viene-rifiutato]
Un push che nomina un'origine dati sconosciuta o in pausa viene risposto con `422 Unprocessable Content`. Il messaggio nomina lo slug e rimanda a **Impostazioni area di lavoro > Origini dati** nella tua area di lavoro, e l'errore in `data` spiega il motivo e cosa fare:
```json
{
"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"
}
}
```
Non riprovare automaticamente questi: hanno successo solo dopo che un amministratore crea o riprende l'origine dati.
## Rimuovi un documento [#rimuovi-un-documento]
`POST /documents/push/delete` (ambito `index:delete`) rimuove un documento inviato tramite il suo `datasource` e `id`. I documenti che smetti di inviare non vengono rimossi automaticamente: elimina ciascuno di quelli che ritiri, oppure invia l'intero elenco dell'origine dati come sessione di caricamento, come descritto sopra.
## Metti in pausa, riprendi ed elimina [#metti-in-pausa-riprendi-ed-elimina]
* **Metti in pausa** rifiuta ogni ulteriore push nell'origine dati. I suoi documenti rimangono ricercabili. Un push già in fase di scrittura quando metti in pausa viene completato.
* **Riprendi** accetta nuovamente i push.
* **Elimina** rimuove l'origine dati e ogni documento inviato ad essa, insieme al loro indice di ricerca. Il tuo sistema mantiene la sua copia, quindi inviarli nuovamente dopo aver ricreato l'origine dati li ripristina. Un'eliminazione non può essere annullata.
Se un altro amministratore ha modificato l'origine dati dopo che hai caricato l'elenco, l'azione viene rifiutata e l'elenco si ricarica, così puoi decidere nuovamente in base a ciò che c'è ora. Ogni creazione, messa in pausa, ripresa ed eliminazione viene registrata nel registro di audit dell'area di lavoro.
L'elenco delle impostazioni mostra a chi è visibile ogni origine dati. Chi può leggere un documento inviato è deciso dal `permissions` inviato con esso; creare, mettere in pausa o eliminare un'origine dati non amplia mai l'accesso a nulla.
Le scritture push sono idempotenti: ripeti lo stesso `Idempotency-Key` in ogni tentativo di una scrittura, e un duplicato viene risposto dal primo tentativo invece di essere applicato due volte. Vedi [Errori e limiti di frequenza](/docs/guides/errors-and-rate-limits).
## Passaggi successivi [#passaggi-successivi]
---
# Filtra e affina la ricerca
Source: https://nordvec.com/it/docs/guides/how-to/filter-search
Restringi una ricerca di documenti con i filtri di origine dati, provider, tipo e data, e leggi i risultati classificati.
`/documents/search` esegue una ricerca full-text sul titolo e sull'intero testo dei
tuoi documenti e restituisce le corrispondenze migliori, ognuna con un punteggio di rilevanza e il
documento sorgente da cui proviene. Questa guida spiega come la query trova le corrispondenze, come restringere i risultati con i filtri e come leggere la risposta.
## La richiesta [#la-richiesta]
Solo `query` è obbligatorio. Tutto il resto restringe o limita i risultati.
```bash
curl https://nordvec.com/api/v1/documents/search \
-H "Authorization: Bearer $NORDVEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "renewal terms",
"limit": 20,
"datasource": "contracts",
"sourceProvider": "google",
"createdAfter": "2026-01-01T00:00:00Z",
"createdBefore": "2026-07-01T00:00:00Z"
}'
```
| Campo | Tipo | Note |
| ---------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | stringa | Obbligatorio. Da 1 a 500 caratteri. Sono supportate frasi tra virgolette, `or` e un `-` iniziale per escludere una parola. |
| `limit` | intero | Facoltativo. Da 1 a 50, predefinito 20. Numero di risultati da restituire. |
| `datasource` | stringa | Facoltativo. Limita a una singola origine dati tramite il suo slug (fino a 200 caratteri). |
| `sourceProvider` | stringa | Facoltativo. Limita a un singolo provider di connettore, ad esempio `google`, `sharepoint` o `slack`. |
| `createdAfter` | stringa | Facoltativo. Timestamp ISO 8601 con offset; solo documenti creati in questa data o successivamente. |
| `createdBefore` | stringa | Facoltativo. Timestamp ISO 8601 con offset; solo documenti creati in questa data o precedentemente. |
| `contentType` | stringa | Facoltativo. Limita a un singolo tipo di conoscenza, il `type` dichiarato da un documento inviato o da un file di conoscenza (ad esempio `policy` o `runbook`). |
Ogni filtro è combinato con AND: un documento deve corrispondere alla query **e** a ogni
filtro che fornisci. Ometti un filtro per ampliare la ricerca.
## Come la query trova le corrispondenze [#come-la-query-trova-le-corrispondenze]
* **Viene cercato l'intero documento.** Contano il titolo e ogni passaggio del testo,
indipendentemente dalla lunghezza del documento.
* **Le parole corrispondono nella forma in cui le scrivi, in qualsiasi lingua.** Non c'è
stemming: `invoice` non corrisponde a `invoices`, e `tilbagebetaling` non
corrisponde a `tilbagebetalingen`. Per includere più forme, uniscile con `or`.
* **Gli accenti sono ignorati su entrambi i lati.** `cafe` trova `café`, e `børnehave`
e `bornehave` si trovano a vicenda. Anche le maiuscole/minuscole sono ignorate.
* **Operatori.** Metti le parole tra virgolette doppie per trovarle come frase, scrivi
`or` tra le parole per trovare l'una o l'altra, e metti `-` prima di una parola per escludere
i documenti che la contengono.
## Prova [#prova]
Dopo aver effettuato l'accesso, puoi eseguire una ricerca sui tuoi documenti da questa pagina. Modifica
la query nella reference API per provare con le tue.
Try it in the API reference: [`POST /api/v1/documents/search`](https://nordvec.com/docs/api#tag/documents/POST/documents/search) (Search documents).
## La risposta [#la-risposta]
```json
{
"results": [
{
"id": "0198f2a4-6c1e-7d30-b6a1-2f9d54c08a11",
"title": "Acme Corp Master Services Agreement",
"snippet": "Automatic **renewal**: the agreement continues for successive twelve month **terms** unless…",
"score": 0.82,
"datasource": "contracts",
"source_provider": "google",
"source_type": null,
"mime_type": "application/pdf",
"content_type": null,
"status": "indexed",
"created_at": "2026-02-14T09:00:00Z",
"updated_at": "2026-02-14T09:00:00Z"
}
],
"totalCount": 7
}
```
Ogni risultato è un documento. Il suo `snippet` è estratto dal passaggio che ha avuto la corrispondenza migliore,
ovunque si trovi nel testo, con le parole corrispondenti racchiuse in
`**`; una parola che hai digitato senza accenti viene trovata e classificata, ma potrebbe apparire
senza evidenziazione nello snippet. Il `score` va da 0 fino a, ma senza raggiungere, 1
(più alto è più rilevante), e i metadati del documento sorgente ti permettono di risalire
al risultato. `totalCount` indica quanti documenti hanno avuto corrispondenza in totale, che può
essere maggiore del numero di `results` che hai richiesto con `limit`.
## Lettura dei risultati [#lettura-dei-risultati]
* **I risultati sono ordinati per rilevanza**, dal più rilevante al meno rilevante. Un documento è classificato in base
al suo passaggio con la corrispondenza migliore. Usa `score` per escludere corrispondenze deboli all'interno di un insieme di
risultati; i punteggi di query diverse non sono sulla stessa scala.
* **`totalCount` vs `results.length`**: `results` contiene fino a `limit` elementi;
`totalCount` è il conteggio totale delle corrispondenze. Se `totalCount` è molto più grande del tuo
`limit`, restringi la `query` o aggiungi un filtro; non esiste una seconda pagina di
risultati di ricerca.
* **`status` ti dice dove si trova il documento nel processo di elaborazione.** Un documento viene
abbinato in base al testo memorizzato, quindi uno ancora `processing` può apparire; `indexed`
significa che ogni passaggio è stato completato. Vedi
[Documenti e ricerca](/docs/guides/concepts/documents) per il ciclo di vita.
La ricerca restituisce solo documenti che l'utente che chiama è autorizzato a vedere. L'accesso è
applicato nel database, non nel codice dell'applicazione, quindi un filtro non può mai ampliare
ciò che l'utente vede. Per una chiave API, questo corrisponde a ciò che condivide l'area di lavoro; vedi
[Chi vede un documento](/docs/guides/concepts/documents#who-sees-a-document).
## Passaggi successivi [#passaggi-successivi]
---
# Elenca e recupera i documenti
Source: https://nordvec.com/it/docs/guides/how-to/list-documents
Scorri i tuoi documenti con la paginazione tramite cursore, filtrali e ordinali, e recuperane uno o molti tramite id.
Mentre la [ricerca](/docs/guides/how-to/filter-search) ordina i documenti in base alla rilevanza rispetto a una query, il listing scorre tutto il tuo corpus in ordine. Usalo per sincronizzare, verificare o costruire il tuo indice su ciò che Nordvec contiene. Il listing restituisce solo i metadati, non il contenuto dei documenti.
## List con paginazione tramite cursore [#list-con-paginazione-tramite-cursore]
`/documents/list` restituisce una pagina di documenti più un `nextCursor` opaco. Passa quel cursore per ottenere la pagina successiva e fermati quando `hasMore` è `false`.
```bash
curl "https://nordvec.com/api/v1/documents/list?limit=50" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
```json
{
"items": [
{ "id": "…", "title": "Q3 Financial Report", "status": "indexed", "datasource": "finance", "created_at": "2026-04-01T10:00:00Z" }
],
"nextCursor": "eyJrIjoi…",
"hasMore": true
}
```
Dopo aver effettuato l'accesso, puoi elencare la prima pagina dei tuoi documenti da qui:
Try it in the API reference: [`GET /api/v1/documents/list`](https://nordvec.com/docs/api#tag/documents/GET/documents/list) (List documents).
Per scorrere ogni pagina, ripeti il ciclo finché `hasMore` è `false`, passando ogni volta il `nextCursor` della risposta precedente, con lo stesso `sort` e `direction`:
```bash
curl "https://nordvec.com/api/v1/documents/list?limit=50&cursor=eyJrIjoi…" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
Il cursore è opaco, non analizzarlo né costruirlo. Passa indietro esattamente ciò che la risposta precedente ha restituito. Un cursore non valido, o uno proveniente da un diverso ordine di ordinamento, viene rifiutato.
## Filtra e ordina [#filtra-e-ordina]
Tutti i filtri sono opzionali e si combinano con AND. L'ordinamento predefinito è dal più recente al più vecchio.
| Campo | Tipo | Note |
| -------------------------------- | ------- | ----------------------------------------------------------------------------- |
| `limit` | integer | Da 1 a 200 (predefinito 50). |
| `cursor` | string | Cursore opaco della pagina precedente. |
| `datasource` | string | Limita a una singola origine dati tramite il suo slug (fino a 200 caratteri). |
| `status` | enum | `indexed`, `processing` o `failed`. |
| `sourceProvider` | string | Limita a un singolo provider di connettori, ad esempio `google` o `slack`. |
| `contentType` | string | Limita a un singolo tipo di conoscenza, ad esempio `policy` o `runbook`. |
| `createdAfter` / `createdBefore` | string | Timestamp ISO 8601 con offset, entrambi inclusi. |
| `sort` | enum | `createdAt` (predefinito), `updatedAt` o `title`. |
| `direction` | enum | `desc` (predefinito) o `asc`. |
```bash
curl "https://nordvec.com/api/v1/documents/list?status=indexed&datasource=finance&sort=updatedAt&direction=desc&limit=100" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
### Quale ordinamento usare per lo scorrimento [#quale-ordinamento-usare-per-lo-scorrimento]
* **Enumerazione completa in un'unica soluzione**: `sort=createdAt`. L'orario di creazione non cambia mai, quindi ogni documento appare esattamente una volta.
* **Aggiornamento incrementale da un watermark**: `sort=updatedAt&direction=asc`. Un documento aggiornato mentre lo scorri può apparire due volte, quindi esegui l'upsert tramite `id`.
* **Ordine di visualizzazione**: `updatedAt` o `title` decrescente. Un documento aggiornato tra due pagine può spostarsi oltre il cursore e essere saltato, quindi non usarlo per l'enumerazione.
## Recupera un singolo documento [#recupera-un-singolo-documento]
`/documents/{id}` restituisce i metadati, lo stato di elaborazione e il testo di un documento. Un testo lungo può essere letto in finestre: `contentOffset` e `contentMaxChars` (contati in unità di codice UTF-16) selezionano una finestra, e `content_range` riporta la finestra e la lunghezza totale, quindi continua a leggere finché `offset + length` non raggiunge `total`.
```bash
curl "https://nordvec.com/api/v1/documents/DOCUMENT_ID?contentMaxChars=100000" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
## Recupera molti documenti in una volta sola [#recupera-molti-documenti-in-una-volta-sola]
Per risolvere fino a 200 ID in una singola chiamata, inviali tramite POST a `/documents/batch` invece di effettuare una richiesta per ogni ID. Il batch restituisce metadati e stato di elaborazione; `content` è sempre `null`, quindi leggi il testo con la chiamata per il singolo documento.
```bash
curl https://nordvec.com/api/v1/documents/batch \
-H "Authorization: Bearer $NORDVEC_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "ids": ["DOCUMENT_ID_1", "DOCUMENT_ID_2"] }'
```
Il listing, come la ricerca, restituisce solo i documenti che l'utente è autorizzato a vedere. `status` ti indica in quale fase di elaborazione si trova un documento: `processing` mentre è ancora in fase di indicizzazione, `failed` se non è stato possibile elaborarlo. Consulta [Documenti e ricerca](/docs/guides/concepts/documents) per il ciclo di vita.
## Passaggi successivi [#passaggi-successivi]