# Context pack: Lähetä dokumentteja omista järjestelmistäsi
Source: https://nordvec.com/fi/docs/guides/how-to/push-documents
Pack: https://nordvec.com/fi/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. [Tunnistautuminen](https://nordvec.com/fi/docs/guides/authentication) (builds on)
2. [Virheet ja rajojen ylitykset](https://nordvec.com/fi/docs/guides/errors-and-rate-limits) (builds on)
3. [Lähetä dokumentteja omista järjestelmistäsi](https://nordvec.com/fi/docs/guides/how-to/push-documents) (this guide)
4. [Suodata ja tarkenna hakua](https://nordvec.com/fi/docs/guides/how-to/filter-search) (linked from this guide)
5. [Listaa ja hae dokumentteja](https://nordvec.com/fi/docs/guides/how-to/list-documents) (linked from this guide)
---
# Tunnistautuminen
Source: https://nordvec.com/fi/docs/guides/authentication
Tunnistaudu Nordvecin API-pyyntöihin lähettämällä työtilan API-avain kantoavaan tunnisteeseen ja valitse työn tarvitsema avainluokka sekä käyttöoikeudet.
Ohjelma kutsuu Nordvec API:a **API-avaimella**, joka lähetetään bearer-tokenina `Authorization`-otsakkeessa.
```bash
curl https://nordvec.com/api/v1/documents/list \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
Kaikki päätepisteet eivät vaadi avainta. Keskustelut, webhookit ja avainten hallinta kuuluvat kirjautuneelle henkilölle ja vastaavat vain istuntoon. [API-viite](/docs/api) merkitsee jokaisen operaation sen hyväksymillä tunnistetiedoilla.
## Avaimen luokat [#avaimen-luokat]
Avain kuuluu johonkin kahdesta luokasta, ja sen etuliite kertoo, kumpaan:
| Luokka | Etuliite | Käyttötarkoitus |
| -------- | ------------- | ---------------------------------------------------------------------------------------------------- |
| Client | `nv_eu_live_` | Lukeminen: dokumenttien haku, listaaminen ja nouto, kiintiöt, audittijälki |
| Indexing | `nv_eu_idx_` | Kirjoittaminen: dokumenttien lähetys, poisto ja käyttöoikeuksien muuttaminen, sisäänsyötön tarkistus |
## Käyttöoikeudet [#käyttöoikeudet]
Avaimella on yksi tai useampi käyttöoikeus, ja operaatio vastaa `403` avaimelle, jolta puuttuu tarvitsemansa käyttöoikeus. Avain voi sisältää vain oman luokkansa käyttöoikeuksia.
| Käyttöoikeus | Luokka | Sallii |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `search:read` | Client | Dokumenttien haku, listaaminen, nouto ja erä-nouto |
| `quota:read` | Client | Upotusten kiintiöt ja käytön analytiikka |
| `audit:read` | Client | Työtilan audittijäljen haku ja tapahtumakatalogin lukeminen |
| `index:write` | Indexing | Dokumenttien lähetys ja erälähetys, niiden käyttöoikeuksien päivittäminen |
| `index:delete` | Indexing | Lähetettyjen dokumenttien poistaminen |
| `index:status` | Indexing | Lähetystilan ja sisäänsyötön tilan tarkistus |
| `index:acl-widen` | Indexing | Jo rajoitetun dokumentin näkyväksi tekeminen koko työtilalle. Avaimella, jolla on tämä käyttöoikeus, on oltava voimassaoloaika |
Anna jokaiselle avaimelle mahdollisimman vähän käyttöoikeuksia, jotta vuotanut avain voi tehdä mahdollisimman vähän vahinkoa.
## Avaimen luominen [#avaimen-luominen]
Luo avain kohdassa **Asetukset > API-avaimet**. Avaimen luominen vaatii työtilan **omistajan** tai **ylläpitäjän** roolin. Henkilökohtaisessa työtilassa olet itse tämä henkilö. **Raaka-avain palautetaan täsmälleen kerran**, eikä sitä voi hakea myöhemmin, joten kopioi se salaisuuksien tallennuspaikkaan heti.
Avain kuuluu työtilaan, ei sitä luoneeseen henkilöön. Se lukee työtilan jakamia dokumentteja: dokumentit, jotka henkilö on yhdistänyt mutta ei jakanut, näkyvät vain kyseiselle henkilölle, eikä mikään avain voi nähdä niitä.
Avaimella voi olla myös voimassaoloaika (1–3650 päivää) ja IP-sallittulista, johon voi lisätä enintään 50 osoitetta tai CIDR-aluetta.
## Avaimen vaihtaminen ja peruuttaminen [#avaimen-vaihtaminen-ja-peruuttaminen]
Kohtele API-avainta kuin salasanaa. Jos avain vuotaa, vaihda tai peruuta se välittömästi.
* **Vaihto** korvaa avaimen tunnistetiedot paikallaan. Edellinen tunniste toimii vielä valitsemasi siirtymäajan: ei lainkaan, 15 minuuttia, 1 tunti, 6 tuntia tai 24 tuntia (oletus), joten voit ottaa uuden tunnisteen käyttöön palveluissasi keskeytyksettä.
* **Peruutus** poistaa avaimen käytöstä välittömästi, eikä sitä voi enää käyttää tunnistautumiseen.
Molemmat toiminnot vaativat kirjautuneen istunnon (ne eivät ole itse API-avaimella tehtäviä operaatioita), joten vuotanut avain ei voi käyttää itseään vaihtamiseen.
## Hyvät käytännöt [#hyvät-käytännöt]
* Tallenna avaimet salaisuuksien hallintatyökaluun tai ympäristömuuttujaan, älä koskaan lähdekoodiin.
* Käytä erillistä avainta kutakin palvelua tai ympäristöä varten, jotta voit peruuttaa avaimen tarkasti.
* Aseta voimassaoloaika CI- ja skriptikäyttöön tarkoitetuille avaimille.
---
# Virheet ja rajojen ylitykset
Source: https://nordvec.com/fi/docs/guides/errors-and-rate-limits
Yksi virhekuori, jonka jokainen epäonnistunut pyyntö palauttaa, rajojen ylitystiedot otsikoissa ja kuinka kirjoitus voidaan yrittää uudelleen turvallisesti.
Jokainen päätepiste epäonnistuu samalla tavalla, joten asiakas käsittelee virheet, rajoitukset ja uusintayritykset kerran ja käyttää samaa koodia kaikkialla, myös [MCP:n](/docs/guides/mcp) yli.
## Virhekuori [#virhekuori]
Jokainen ei-2xx-vastaus on yksi JSON-objekti:
```json
{
"defined": false,
"code": "TOO_MANY_REQUESTS",
"message": "Too many requests",
"data": { "reason": "rate_limit.exceeded", "retryAfterMs": 12000 }
}
```
* `code` on HTTP-tason virhe, esimerkiksi `UNAUTHORIZED`, `FORBIDDEN`,
`NOT_FOUND`, `BAD_REQUEST` tai `TOO_MANY_REQUESTS`.
* `data.reason`, kun se on olemassa, on tarkempi koneellisesti luettava syy, kuten
`auth.key_not_found` tai `rate_limit.exceeded`. Haaraa sen perusteella eikä `message`:n perusteella,
joka on tarkoitettu ihmisille ja voi muuttua.
* `defined` on `true`, kun toiminto luettelee kyseisen virheen
[API-viitteessä](/docs/api), ja `false` virheille, joita mikä tahansa pyyntö voi kohdata
(todennus, rajoitukset, tuntematon reitti).
* Validointivirhe vastaa `BAD_REQUEST`:llä, ja ongelmat ovat
`data.formErrors`:ssä ja `data.fieldErrors`:ssä.
Jokainen vastaus sisältää myös `X-Request-ID`:n. Mainitse se, kun otat yhteyttä
tukeen, niin löydämme kyseisen pyynnön tarkasti.
## Yleiset tilakoodit [#yleiset-tilakoodit]
| Tilakoodi | Koodi | Toimenpide |
| --------- | ----------------------- | --------------------------------------------------------------------- |
| `400` | `BAD_REQUEST` | Korjaa pyyntö; `data.fieldErrors` nimeää kentät |
| `401` | `UNAUTHORIZED` | Lähetä kelvollinen avain tai istunto |
| `403` | `FORBIDDEN` | Avaimella ei ole vaadittua käyttöoikeutta tai roolia toimintoa varten |
| `404` | `NOT_FOUND` | Resurssia ei ole olemassa, tai sinulla ei ole oikeutta nähdä sitä |
| `409` | `CONFLICT` | Kaksoiskirjoitus on vielä kesken; yritä uudelleen pian |
| `413` | `PAYLOAD_TOO_LARGE` | Pyynnön runko on yli 1 Mt; jaa massapush pienempiin eriin |
| `429` | `TOO_MANY_REQUESTS` | Odota `Retry-After`, sitten yritä uudelleen |
| `422` | `UNPROCESSABLE_CONTENT` | Pyyntö on hyvin muodostettu, mutta sitä ei voida soveltaa |
## Rajoitukset [#rajoitukset]
Jokainen vastaus ilmoittaa rajoituksen, jota vastaan se laskettiin, kahdessa muodossa:
* `X-RateLimit-*`-otsikot;
* IETF:n strukturoidut kentät `RateLimit` (reaaliaikainen tila: `r` on jäljellä olevat pyynnöt,
`t` sekuntia ikkunan nollaukseen) ja `RateLimit-Policy`
(kiintiö: `q` on rajoitus, `w` ikkuna sekunteina).
`429` sisältää myös `Retry-After` sekunteina ja `data.retryAfterMs`. Odota vähintään niin kauan ennen seuraavaa pyyntöä;
aiempi uusintayritys lasketaan ja evätään uudelleen.
## Kirjoitusten turvallinen uusinta [#kirjoitusten-turvallinen-uusinta]
Kirjoitustoiminto, joka luettelee `Idempotency-Key`-otsikon
[API-viitteessä](/docs/api), voidaan uusia ilman, että työ tehdään kahdesti. Lähetä yksi avain loogista kirjoitusta kohden ja toista sama avain jokaisella uusintakerralla:
* sama avain samalla rungolla 24 tunnin sisällä toistaa tallennetun vastauksen;
* sama avain eri rungolla evätään `422`:llä;
* kaksoiskappale, joka saapuu, kun ensimmäinen on vielä käynnissä, saa `409`:n.
Toimintoa, jolla ei ole otsikkoa, ei ole idempotentti, joten yritä sitä uudelleen vain, kun tiedät, että ensimmäinen yritys ei onnistunut.
---
# Lähetä dokumentteja omista järjestelmistäsi
Source: https://nordvec.com/fi/docs/guides/how-to/push-documents
Luo tietolähde, lähetä dokumentteja siihen indeksointiin API-avaimella, valitse, ketkä voivat lukea niitä, ja keskeytä tai poista se, kun lähde muuttuu.
Push-API indeksoi dokumentteja järjestelmistä, joille Nordvecilla ei ole liitintä: sisäisen wikin vienti, tikettiarkisto, muistiinpanojen tietokanta. Lähetät tekstin ja tiedon siitä, kuka saa lukea sitä. Nordvec tallentaa sen EU:hun, indeksoi sen ja tekee siitä haettavan ja siteerattavan kuten mitä tahansa muuta dokumenttia. Jokainen työnnetty dokumentti päätyy **tietolähteeseen**, nimettyyn säilöön työtilassasi, jonka työtilan ylläpitäjä luo ensin. Työntö, joka nimeää tietolähteen, jota ei ole olemassa tai joka on pysäytetty, hylätään.
## Luo tietolähde [#luo-tietolähde]
Avaa **Työtilan asetukset > Tietolähteet** ja valitse **Luo tietolähde**.
Työtilan ylläpitäjät ja omistajat voivat tehdä tämän. Henkilökohtaisessa työtilassa se olet sinä.
| Kenttä | Huomautukset |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Nimi | Näkyy asetuslistassa. Enintään 200 merkkiä. |
| Slug | Jokainen työntö nimeää tämän. Pienet kirjaimet, numerot, `-` ja `_`, alkaa kirjaimella tai numerolla, enintään 200 merkkiä. Sitä ei voi muuttaa myöhemmin. |
Slugia `confluence-export` käytetään esimerkeissä alla.
## Luo indeksointiin API-avain [#luo-indeksointiin-api-avain]
Push-pyynnöt tunnistautuvat **Indeksointi**-luokan API-avaimella, joka sisältää `index:write`-oikeuden. Lisää `index:status` seurantaan ja `index:delete` dokumenttien poistamiseen tai koko tietolähteen korvaamiseen. Luo avain kohdassa **Työtilan asetukset > API-avaimet**. Raaka-avain alkaa `nv_eu_idx_`-merkeillä ja näytetään vain kerran. Katso lisätietoja [Tunnistautuminen](/docs/guides/authentication). Jokainen pyyntö nimeää myös työtilasi tunnuksen `tenantId`, joka on työtilasi osoitteen tunnus sovelluksessa (`/w//...`), ja sen on oltava työtila, johon avain kuuluu.
## Työnnä yksi dokumentti [#työnnä-yksi-dokumentti]
`/documents/push` luo dokumentin tai päivittää sen, jos dokumentti samalla `id`-tunnuksella on jo olemassa tietolähteessä.
```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` on vakaa tunnuksesi dokumentille tietolähteen sisällä. Saman `id`-tunnuksen työntäminen uudelleen päivittää dokumentin. Muuttumaton sisältö tunnistetaan tiivisteensä perusteella eikä sitä indeksoida kahdesti.
* `body.mimeType` on yksi `text/plain`, `text/markdown`, `text/html`, `application/pdf` tai Wordin, Excelin ja PowerPointin (`.docx`, `.xlsx`, `.pptx`) tyyppejä. Binäärisisältö lähetetään base64-koodattuna.
* `sourceUrl` tulee "siirry lähteeseen" -linkiksi jokaisessa dokumentin sitaatissa. Jätä se pois uudelleentyönnössä säilyttääksesi tallennetun linkin tai lähetä `null` tyhjentääksesi sen.
* `type` asettaa dokumentin `content_type`, jota haun ja listan suodattimet käyttävät.
Koko pyynnön runko on rajoitettu 1 Mt:n kokoon, joten suuri tiedosto tai iso erä vastaa `413`-virheellä. Jaa se osiin.
## Valitse, kuka saa lukea dokumenttia [#valitse-kuka-saa-lukea-dokumenttia]
`permissions` on pakollinen jokaisessa työnnössä, joten jakamispäätöstä ei koskaan tehdä jättämällä kenttä pois. Tietolähteessä, joka on näkyvissä työtilalle:
| `permissions` | Kuka saa lukea dokumenttia |
| ----------------------------------------- | ------------------------------------------------------------------ |
| `{}` | Jokainen työtilan jäsen |
| `{ "allowedUsers": ["ana@example.com"] }` | Vain luetellut henkilöt |
| `{ "allowedGroups": ["GROUP_ID"] }` | Näiden työtilaryhmien jäsenet, sisältäen alaryhmät |
| `{ "allowAllTenantMembers": false }` | Hylätään: dokumenttia, jota kukaan ei voi lukea, pidetään poistona |
Muuttaaksesi dokumentin lukuoikeuksia lähettämättä sen sisältöä uudelleen, käytä `POST /documents/push/permissions`-metodia. Jo rajoitetun dokumentin tekeminen näkyväksi koko työtilalle vaatii lisäksi `index:acl-widen`-oikeuden, joten rutiinisynkronointi ei voi hiljaa kumota käsin asetettua rajoitusta.
## Työnnä erissä [#työnnä-erissä]
`/documents/push/bulk` hyväksyy enintään 100 dokumenttia yhdelle tietolähteelle per kutsu. Vastaus laskee `accepted`- ja `rejected`-määrät ja antaa tuloksen dokumenttia kohden, joten yksi virheellinen dokumentti ei epäonnista koko erää. 1 Mt:n rungon raja koskee kutakin kutsua, joten jaa suuret lataukset useisiin kutsuihin saman `uploadId`-tunnuksen alla.
```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": {} }
]
}'
```
## Korvaa koko tietolähde [#korvaa-koko-tietolähde]
Kun järjestelmäsi voi luetella kaiken, mitä tietolähteen tulisi sisältää, lähetä koko luettelo yhtenä **lähetysistuntona**. Istunnon päättyessä tietolähteestä poistetut dokumentit siirretään roskakoriin. Istunnot vaativat indeksointiin tarkoitetun API-avaimen, joka sisältää `index:delete`-oikeuden lisäksi `index:write`-oikeuden, koska istunnon päättyminen poistaa dokumentteja. Avain, jolla istunto avataan, on myös ainoa avain, jolla sitä voi jatkaa.
1. Lähetä ensimmäinen sivu koodilla `"isFirstPage": true`. Se on sivu `0`.
2. Lähetä jokainen seuraava sivu sen `pageIndex`:lla (`1`, `2`, ...), missä järjestyksessä tahansa.
Kahdesti lähetetty sivu lasketaan kerran, joten uudelleenlähetys on aina turvallista.
3. Lähetä viimeinen sivu koodilla `"isLastPage": true` ja sen `pageIndex`:lla. Luettelo,
joka mahtuu yhdelle sivulle, lähettää `isFirstPage`:n ja `isLastPage`:n yhdessä.
Viimeisellä sivulla ei tarvitse olla dokumentteja.
Jokainen sivu käyttää samaa `uploadId`-arvoa, ja jokainen vastaus sisältää istunnon edistymisen `upload`-kohdassa. Istunto päättyy vasta, kun kaikki sivut `0`-arvosta viimeiseen on vastaanotettu. Istunnon päättyessä roskakoriin siirretään jokainen dokumentti, jota mikään istunnon sivu ei maininnut ja joka oli olemassa ennen istunnon avaamista. Mikä tahansa muu push-toiminto tietolähteeseen istunnon aikana säilyttää mainitsemansa dokumentin: yksittäinen push, erä ilman istuntotietoja, käyttöoikeuksien päivitys tai muuttumattoman sisällön uudelleenlähetys. Roskakori säilyttää sinne siirretyt dokumentit 30 päivää. Dokumentin uudelleenlähettäminen palauttaa sen, samoin kuin koko istunnon palauttaminen (katso alla).
Istunto, joka ei saa yhtään sivua 24 tunnin kuluessa, vanhenee ja päättyy poistamatta mitään. Hylätty sivu vastaa koodilla `409 Conflict`, ei kirjoita mitään,
ja sen `data.reason` kertoo syyn:
| `reason` | Toimenpide |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `upload_incomplete` | Lähetä `missingPageIndexes`-kohdassa luetellut sivut ja sen jälkeen viimeinen sivu uudelleen |
| `deletion_confirmation_required` | Istunnon päättyminen siirtäisi roskakoriin yli 20 % tietolähteen dokumenteista. Jos tämä on oikein, lähetä viimeinen sivu uudelleen asettamalla `"confirmDeletions"`-arvoksi `wouldTombstone` |
| `deletion_confirmation_too_large` | `confirmDeletions` on suurempi kuin dokumenttien määrä, joka tietolähteessä oli istunnon avautuessa. Lähetä odottamasi poistettavien dokumenttien määrä |
| `upload_in_progress` | Tietolähteellä on avoin istunto. Jos se on avaimesi istunto, viimeistele se, odota sen vanhenemista tai aloita alusta asettamalla `"forceRestartUpload": true` ensimmäiselle sivulle. Jos toinen avain avasi sen, `forceRestartUpload` korvaa sen vasta, kun se ei ole vastaanottanut sivua tuntiin, `restartableAt`-kohdan ajanhetkestä lähtien |
| `upload_expired`, `upload_missing`, `upload_restarted` | Istunto on poistunut. Aloita uusi istunto uudella `uploadId`-arvolla |
| `upload_closed`, `upload_id_reused` | `uploadId` on käytetty. Käytä uutta avainta |
| `page_index_required` | Avaimellasi on avoin istunto tässä tietolähteessä. Lähetä `pageIndex` sivun kanssa |
Jos haluat jatkaa keskeytyksen jälkeen, lue istunto koodilla
`GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (oikeus `index:status`). Sen `missingPageIndexes` listaa vielä lähettämättömät sivut.
### Peru istunnon päättyminen [#peru-istunnon-päättyminen]
Jos istunto poisti dokumentteja, joita sen ei olisi pitänyt poistaa, esimerkiksi koska lähettämäsi luettelo oli kesken, palauta ne yhdellä kutsulla:
```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" }'
```
Istuntoa avannut avain voi palauttaa sen, ja myös Nordveciin kirjautunut työtilan ylläpitäjä voi palauttaa minkä tahansa avaimen avaaman istunnon. Jokainen istunnon sulkemisen roskakoriin siirtämä dokumentti palautuu sisällöllään, ja vastaus laskee ne: `restored` ovat taas käytössä, `purged` oli jo poistettu pysyvästi roskakorista, ja `skipped` olivat muuttuneet sulkemisen jälkeen (työnnetty uudelleen tai poistettu uudelleen) ja jätettiin sellaisinaan. Istunnon palauttaminen kahdesti vastaa ensimmäisen palautuksen lukumäärillä ja `"replayed": true`, ja laittaa jonoon kaikki palautetut dokumentit, jotka odottavat vielä indeksointia. Siksi palautuksen toistaminen, joka ei vastannut, on turvallista. Istunto voidaan palauttaa 35 päivän ajan sen sulkemisesta, ja niin kauan kuin roskakori sisältää vielä sen poistamia dokumentteja. Kielletty palautus vastaa `409 Conflict` ja sen `data.reason`:llä:
| `reason` | Mitä se tarkoittaa |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `upload_not_closed` | Istuntoa ei ole suljettu, joten se ei poistanut mitään |
| `upload_in_progress` | Tietolähteellä on avoin istunto. Palauta vasta, kun se on suljettu tai vanhentunut |
| `restore_purged` | Yli 30 päivää on kulunut, ja roskakori on poistanut jokaisen dokumentin. Työnnä ne uudelleen |
| `workspace_not_entitled` | Työtilan suunnitelma ei tällä hetkellä salli palautusta roskakorista |
| `corpus_cap_exceeded` | Dokumenttien palauttaminen ylittäisi työtilan dokumenttirajan, joten yksikään ei palautunut. `data.wouldRestore` on kuinka monta tarvittaisiin ja `data.headroom` kuinka monta mahtuu. Vapauta tilaa, sitten palauta uudelleen |
## Seuraa indeksointia [#seuraa-indeksointia]
Työntö vastaa heti, kun dokumentti on asetettu jonoon. Kysy sen edistymistä `GET /documents/push/status`-kutsulla (oikeus `index:status`), suodatettuna tietolähteen tai dokumenttitunnuksen perusteella. Dokumentti siirtyy tilasta `queued` tilan `processing` kautta tilaan `completed` tai tilaan `failed` virheellä `error`.
## Kun työntö hylätään [#kun-työntö-hylätään]
Työntö, joka nimeää tuntemattoman tai pysäytetyn tietolähteen, vastaa `422 Unprocessable Content`-virheellä. Viesti nimeää slugin ja linkittää **Workspace settings > Datasources** -sivulle työtilassasi, ja virheen `data` kertoo syyn ja mitä tehdä:
```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"
}
}
```
Älä yritä näitä automaattisesti uudelleen: ne onnistuvat vasta, kun ylläpitäjä luo tai jatkaa tietolähdettä.
## Poista dokumentti [#poista-dokumentti]
`POST /documents/push/delete` (scope `index:delete`) poistaa työntämäsi dokumentin sen `datasource` ja `id` perusteella. Dokumentit, joiden työntämisen lopetat, eivät poistu itsestään: poista jokainen dokumentti, jonka käytöstä poistat, tai lähetä tietolähteen koko luettelo latausistuntona, kuten edellä on kuvattu.
## Pysäytä, jatka ja poista [#pysäytä-jatka-ja-poista]
* **Pysäytä** hylkää jokaisen jatkotyönnön tietolähteeseen. Sen dokumentit pysyvät haettavina. Työntö, joka on jo kirjoituksessa pysäytyksen hetkellä, valmistuu.
* **Jatka** hyväksyy työnnöt jälleen.
* **Poista** poistaa tietolähteen ja kaikki siihen työnnetyt dokumentit sekä niiden hakukannan. Oman järjestelmäsi kopio säilyy, joten työntämällä uudelleen tietolähteen luomisen jälkeen ne palautuvat. Poistoa ei voi peruuttaa.
Jos toinen ylläpitäjä on muuttanut tietolähdettä listan lataamisen jälkeen, toiminto hylätään ja lista latautuu uudelleen, joten päätät uudelleen sen perusteella, mikä on nyt voimassa. Jokainen luonti, pysäytys, jatkaminen ja poisto kirjataan työtilan tarkastuslokiin.
Asetuslista näyttää, kenelle kukin tietolähde on näkyvissä. Kuka saa lukea työnnettyä dokumenttia, päätetään `permissions`:n perusteella, joka lähetetään sen mukana. Tietolähteen luominen, pysäyttäminen tai poistaminen ei koskaan laajenna pääsyä mihinkään.
Työntöjen kirjoitukset ovat idempotentteja: toista sama `Idempotency-Key` jokaisella yhden kirjoituksen uudelleenyrittämällä, ja kaksoiskappale vastaa ensimmäisestä yrityksestä sen sijaan, että sitä sovellettaisiin kahdesti. Katso lisätietoja [Virheistä ja nopeusrajoituksista](/docs/guides/errors-and-rate-limits).
## Seuraavat vaiheet [#seuraavat-vaiheet]
---
# Suodata ja tarkenna hakua
Source: https://nordvec.com/fi/docs/guides/how-to/filter-search
Kavenna dokumenttihakua tietolähteen, tarjoajan, tyypin ja päivämäärän suodattimilla ja lue järjestetyt tulokset.
`/documents/search` suorittaa koko tekstin haun dokumenttiesi otsikosta ja koko tekstistä, ja palauttaa parhaat osumat, joista jokaisessa on relevanssipisteet ja lähdedokumentti, josta se on peräisin. Tämä opas näyttää, miten kysely osuu kohdalleen, miten tuloksia rajataan suotimilla ja miten vastaus tulkitaan.
## Pyyntö [#pyyntö]
Vain `query` on pakollinen. Kaikki muu rajaa tai asettaa tuloksille rajat.
```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"
}'
```
| Kenttä | Tyyppi | Huomautukset |
| ---------------- | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `query` | merkkijono | Pakollinen. 1–500 merkkiä. Lainatut fraasit, `or` ja alussa oleva `-` poissulkevan sanan merkiksi ymmärretään. |
| `limit` | kokonaisluku | Valinnainen. 1–50, oletus 20. Kuinka monta tulosta palautetaan. |
| `datasource` | merkkijono | Valinnainen. Rajaa yhteen tietolähteeseen sen tunnisteen (slug) perusteella (enintään 200 merkkiä). |
| `sourceProvider` | merkkijono | Valinnainen. Rajaa yhteen liittimen tarjoajaan, esimerkiksi `google`, `sharepoint` tai `slack`. |
| `createdAfter` | merkkijono | Valinnainen. ISO 8601 -aikaleima aikavyöhykkeen kanssa; vain dokumentit, jotka on luotu sen jälkeen tai sillä hetkellä. |
| `createdBefore` | merkkijono | Valinnainen. ISO 8601 -aikaleima aikavyöhykkeen kanssa; vain dokumentit, jotka on luotu ennen sitä tai sillä hetkellä. |
| `contentType` | merkkijono | Valinnainen. Rajaa yhteen tietotyyppiin, `type`, jonka työnnetty dokumentti tai tietotiedosto ilmoittaa (esimerkiksi `policy` tai `runbook`). |
Jokainen suodin yhdistetään JA-operaattorilla: dokumentin on vastattava kyselyä **ja** jokaista antamaasi suodinta. Jätä suodin pois laajentaaksesi hakua.
## Miten kysely osuu kohdalleen [#miten-kysely-osuu-kohdalleen]
* **Koko dokumenttia haetaan.** Otsikko ja jokainen tekstikappale otetaan huomioon, riippumatta dokumentin pituudesta.
* **Sanat osuvat muotoon, jonka kirjoitat, millä tahansa kielellä.** Sanavartaloita ei tunnisteta: `invoice` ei osu `invoices`:een, ja `tilbagebetaling` ei osu `tilbagebetalingen`:een. Useiden muotojen löytämiseksi yhdistä ne `or`-merkillä.
* **Painomerkit jätetään huomiotta molemmin puolin.** `cafe` löytää `café`:n, ja `børnehave` ja `bornehave` löytävät toisensa. Myös isot ja pienet kirjaimet jätetään huomiotta.
* **Operaattorit.** Laita sanat lainausmerkkeihin, jotta ne osuvat fraasina, kirjoita `or` sanojen väliin, jotta osuu jompikumpi, ja laita `-` sanan eteen, jotta jätetään pois dokumentit, jotka sisältävät sen.
## Kokeile [#kokeile]
Kirjautuneena voit suorittaa haun omista dokumenteistasi tältä sivulta. Muuta kyselyä API-viitteessä kokeillaksesi omia kyselyitäsi.
Try it in the API reference: [`POST /api/v1/documents/search`](https://nordvec.com/docs/api#tag/documents/POST/documents/search) (Search documents).
## Vastaus [#vastaus]
```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
}
```
Jokainen tulos on yksi dokumentti. Sen `snippet` on leikattu parhaiten osuvasta kohdasta, missä tahansa tekstissä se sijaitseekin, ja osuvat sanat on kiedottu `**`-tageihin. Sana, jonka kirjoitit ilman painomerkkejä, löytyy ja pisteytetään, mutta se saattaa näkyä merkitsemättömänä katkelmassa. `score` on välillä 0–1 (suurempi on relevantimpi), eikä se koskaan saavuta arvoa 1, ja lähdedokumentin metatiedot auttavat jäljittämään tuloksen taakse. `totalCount` kertoo, kuinka monta dokumenttia osui yhteensä, mikä voi olla suurempi kuin `results`-määrä, jonka pyysit `limit`-parametrilla.
## Tulosten tulkinta [#tulosten-tulkinta]
* **Tulokset on järjestetty relevanssin mukaan**, relevantimmat ensin. Dokumentti pisteytetään parhaiten osuvan kohdan perusteella. Käytä `score`-parametria heikkojen osumien pudottamiseen yhden tulossarjan sisällä; eri kyselyjen pisteet eivät ole samalla asteikolla.
* **`totalCount` vs `results.length`**: `results` sisältää enintään `limit` kohdetta; `totalCount` on täysi osumamäärä. Jos `totalCount` on paljon suurempi kuin `limit`, tiukenna `query` tai lisää suodin; hakutuloksissa ei ole toista sivua.
* **`status` kertoo, missä vaiheessa dokumentin käsittely on.** Dokumenttia verrataan sen tallennettuun tekstiin, joten vielä `processing` oleva dokumentti voi näkyä; `indexed` tarkoittaa, että kaikki vaiheet on suoritettu. Katso [Dokumentit & haku](/docs/guides/concepts/documents) dokumentin elinkaaresta.
Haku palauttaa aina vain dokumentteja, joita kutsujalla on lupa nähdä. Pääsyoikeuksia valvotaan tietokannassa, ei sovelluskoodissa, joten suodin ei voi koskaan laajentaa sitä, mitä kutsuja näkee. API-avaimen tapauksessa tämä on se, mitä työtila jakaa; katso [Kuka näkee dokumentin](/docs/guides/concepts/documents#who-sees-a-document).
## Seuraavat vaiheet [#seuraavat-vaiheet]
---
# Listaa ja hae dokumentteja
Source: https://nordvec.com/fi/docs/guides/how-to/list-documents
Selaa dokumenttejasi kursori-pohjaisella sivutuksella, suodata ja lajittele niitä sekä hae yhtä tai useampaa tunnisteen perusteella.
Kun [haku](/docs/guides/how-to/filter-search) järjestää dokumentit kyselyn relevanssin mukaan, listaus käy läpi koko tietokantasi järjestyksessä. Käytä sitä synkronoimiseen, tarkistamiseen tai oman indeksisi rakentamiseen siitä, mitä Nordvec sisältää. Listaus palauttaa vain metatiedot, ei dokumentin sisältöä.
## Listaus osoittimen avulla [#listaus-osoittimen-avulla]
`/documents/list` palauttaa sivun dokumentteja sekä läpinäkymättömän `nextCursor`-osoittimen. Lähetä tämä osoitin takaisin saadaksesi seuraavan sivun, ja lopeta, kun `hasMore` on `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
}
```
Kirjautuneena voit listata ensimmäisen sivun omia dokumenttejasi täältä:
Try it in the API reference: [`GET /api/v1/documents/list`](https://nordvec.com/docs/api#tag/documents/GET/documents/list) (List documents).
Käydäksesi läpi kaikki sivut, toista silmukkaa, kunnes `hasMore` on `false`, lähettämällä aina edellisen vastauksen `nextCursor` sekä samat `sort` ja `direction`:
```bash
curl "https://nordvec.com/api/v1/documents/list?limit=50&cursor=eyJrIjoi…" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
Osoitin on läpinäkymätön, älä parsioi tai rakenna sitä. Lähetä takaisin täsmälleen se, mitä edellinen vastaus palautti. Virheellinen osoitin tai sellainen, joka on peräisin eri lajittelujärjestyksestä, hylätään.
## Suodatus ja lajittelu [#suodatus-ja-lajittelu]
Kaikki suodattimet ovat valinnaisia ja yhdistyvät AND-operaattorilla. Oletuslajittelu on uusin ensin.
| Kenttä | Tyyppi | Huomautukset |
| -------------------------------- | ------------ | -------------------------------------------------------------------------------------- |
| `limit` | kokonaisluku | 1–200 (oletus 50). |
| `cursor` | merkkijono | Läpinäkymätön osoitin edelliseltä sivulta. |
| `datasource` | merkkijono | Rajaa yhteen tietolähteeseen sen tunnisteen (slug) perusteella (enintään 200 merkkiä). |
| `status` | enum | `indexed`, `processing` tai `failed`. |
| `sourceProvider` | merkkijono | Rajaa yhteen liittimeen, esimerkiksi `google` tai `slack`. |
| `contentType` | merkkijono | Rajaa yhteen tietotyyppiin, esimerkiksi `policy` tai `runbook`. |
| `createdAfter` / `createdBefore` | merkkijono | ISO 8601 -aikaleimat aikavyöhykkeen kanssa, molemmat mukaan lukien. |
| `sort` | enum | `createdAt` (oletus), `updatedAt` tai `title`. |
| `direction` | enum | `desc` (oletus) tai `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"
```
### Mikä lajittelu kannattaa valita kävelyyn [#mikä-lajittelu-kannattaa-valita-kävelyyn]
* **Täydellinen, kertaluonteinen luettelo**: `sort=createdAt`. Luontiaika ei muutu, joten jokainen dokumentti esiintyy täsmälleen kerran.
* **Inkrementaalinen päivitys vesileimasta**: `sort=updatedAt&direction=asc`. Dokumentti, jota päivitetään kävelyn aikana, voi esiintyä kahdesti, joten lisää tai päivitä `id`-kentän perusteella.
* **Näyttöjärjestys**: `updatedAt` tai `title` laskevassa järjestyksessä. Dokumentti, jota päivitetään kahden sivun välillä, voi siirtyä osoittimen ohi ja jäädä välistä, joten älä käytä sitä luetteloimiseen.
## Yhden dokumentin hakeminen [#yhden-dokumentin-hakeminen]
`/documents/{id}` palauttaa yhden dokumentin metatiedot, käsittelytilan ja tekstin. Pitkä teksti voidaan lukea ikkunoittain: `contentOffset` ja `contentMaxChars` (laskettuna UTF-16-koodiyksiköissä) valitsevat yhden ikkunan, ja `content_range` raportoi ikkunan sekä koko pituuden. Jatka lukemista, kunnes `offset + length` saavuttaa `total`.
```bash
curl "https://nordvec.com/api/v1/documents/DOCUMENT_ID?contentMaxChars=100000" \
-H "Authorization: Bearer $NORDVEC_API_KEY"
```
## Useiden dokumenttien hakeminen kerralla [#useiden-dokumenttien-hakeminen-kerralla]
Jos haluat hakea enintään 200 tunnusta yhdellä kutsulla, lähetä ne POST-pyynnöllä `/documents/batch`-osoitteeseen yhden pyynnön sijaan. Erä palauttaa metatiedot ja käsittelytilan. `content` on aina `null`, joten lue teksti yhden dokumentin kutsulla.
```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"] }'
```
Listaus, kuten haku, palauttaa vain dokumentit, joihin pyynnön tekijällä on oikeus nähdä. `status` kertoo, missä vaiheessa dokumentin käsittely on: `processing`, kun sitä vielä indeksoidaan, ja `failed`, jos sitä ei voitu käsitellä. Katso lisätietoja [Dokumentit ja haku](/docs/guides/concepts/documents)-sivulta.
## Seuraavat vaiheet [#seuraavat-vaiheet]