# Context pack: Documents & search

Source: https://nordvec.com/docs/guides/concepts/documents
Pack: https://nordvec.com/docs/packs/concepts/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. [Documents & search](https://nordvec.com/docs/guides/concepts/documents) (this guide)
2. [Conversations & citations](https://nordvec.com/docs/guides/concepts/conversations) (linked from this guide)
3. [Push documents from your own systems](https://nordvec.com/docs/guides/how-to/push-documents) (linked from this guide)
4. [Connectors](https://nordvec.com/docs/guides/connectors) (linked from this guide)

---

# Documents & search
Source: https://nordvec.com/docs/guides/concepts/documents

Documents are the searchable unit in Nordvec. Ingest them, then find them with full-text search over the API.

A **document** is the unit Nordvec searches over: a file, a page, a message, an
email, whatever you ingest. Once a document is processed it becomes searchable
and can be cited in an answer.

## Ingesting documents [#ingesting-documents]

Documents enter your workspace three ways:

- **Connectors** sync from a source you own (the connector owner). New and
  changed documents are picked up automatically. See the
  [connector catalogue](/docs/guides/connectors).
- **Uploads** of files you add in the app.
- **Push** sends a document to Nordvec directly from your own system. See
  [Push documents](/docs/guides/how-to/push-documents).

Whichever way it arrives, Nordvec processes the document, splits it into passages, and indexes
it for retrieval. Your documents are stored and searched in the EU.

A document has a `status`: `processing` while it is being indexed, `indexed`
once every processing step has finished, and `failed` when it could not be processed.

## Who sees a document [#who-sees-a-document]

A document from a connector is private to the person who connected it until
that person shares it. An API key belongs to the workspace, so it sees what the
workspace shares and never a person's unshared documents.

## Searching [#searching]

`/documents/search` is **full-text** search over the title and the whole text
of every document you can see, however long the document is. Words match in the
form you write them, in any language, and accents are ignored on both sides, so
`cafe` finds `café`. There is no stemming: `invoice` does not match `invoices`.

Search runs standalone, without conversation context. It returns ranked
documents, each with a snippet from its best-matching passage and a relevance
score from 0 up to, but never reaching, 1.

```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": 10 }'
```

You can also list documents (`/documents/list`) or fetch one by id
(`/documents/{id}`). See the [API reference](/docs/api) for the full set of
parameters and response shapes.

### Try it [#try-it]

Run a query against a small demo corpus. This searches six sample documents in
your browser, ranked and sourced, the same shape a real search returns.

<LiveSearchDemo />

Semantic retrieval, which matches passages by meaning rather than exact words,
is what powers a [conversation's](/docs/guides/concepts/conversations) cited
answers. The search endpoint itself matches words.

<Callout>
Search only ever returns documents the caller is allowed to see. Access is
enforced in the database, not in application code.
</Callout>

## Content types [#content-types]

A document can carry a knowledge type in `content_type` (for example
`decision`, `runbook`, `policy` or `faq`). A pushed document sets it with the
push API's `type`; a document with no type has `content_type: null`. Search and
list both filter on it with `contentType`.

## Where documents are cited [#where-documents-are-cited]

Search gives you passages to work with directly. When you want a written answer
instead of raw passages, a [conversation](/docs/guides/concepts/conversations)
retrieves over the same documents and cites them in its reply.


---

# Conversations & citations
Source: https://nordvec.com/docs/guides/concepts/conversations

A conversation is a chat grounded in your documents, where every answer is traced to its source.

A **conversation** is a chat grounded in your documents. You ask a question,
Nordvec retrieves the relevant passages, and it answers from them, citing the
documents it used. If the documents do not support an answer, it says so rather
than guessing.

## Citations are the point [#citations-are-the-point]

Every answer carries the sources it was built from. This is deliberate: a RAG
answer you cannot trace is a liability, not a feature. The citations let a human
jump to the exact document a claim came from and confirm it, which is exactly
what regulated and high-stakes work needs.

<Callout>
Answers are generated by AI. Citations are what make them verifiable, not just
plausible.
</Callout>

## Conversations belong to a person [#conversations-belong-to-a-person]

A conversation is owned by the signed-in person who started it, so its
endpoints answer to a **session**, never to an API key. A key is its own
principal with no chat history of its own; see
[Authentication](/docs/guides/authentication).

With a session you can:

- **Create** a conversation (`POST /conversations`).
- **List** and **search** your conversations (`GET /conversations`,
  `GET /conversations/search`).
- **Retrieve** a conversation with its recent messages
  (`GET /conversations/{id}`), and page back through older history
  (`GET /conversations/{id}/messages`).
- **List the documents** a conversation has drawn on
  (`GET /conversations/{id}/documents`).

See the [API reference](/docs/api) for the exact request and response shapes.

## Feedback [#feedback]

You can submit feedback on an answer and on the passages that were retrieved.
That signal is used to improve retrieval quality over time.


---

# Push documents from your own systems
Source: https://nordvec.com/docs/guides/how-to/push-documents

Create a datasource, push documents into it with an indexing API key, choose who can read them, and pause or delete it when the source changes.

The push API indexes documents from systems Nordvec has no connector for: an
internal wiki export, a ticket archive, a database of notes. You send the text
and who may read it; Nordvec stores it in the EU, indexes it, and makes it
searchable and citable like any other document. Every pushed document lands in
a **datasource**, a named container in your workspace that a workspace admin
creates first. A push that names a datasource which does not exist, or one that
is paused, is refused.

## Create a datasource [#create-a-datasource]

Open **Workspace settings > Datasources** and choose **Create datasource**.
Workspace admins and owners can do this; in a personal workspace, that is you.

| Field | Notes |
|---|---|
| Name | What people see in the settings list. Up to 200 characters. |
| Slug | What every push names. Lowercase letters, digits, `-` and `_`, starting with a letter or digit, up to 200 characters. It cannot be changed later. |

The slug `confluence-export` is used in the examples below.

## Create an indexing API key [#create-an-indexing-api-key]

Pushes authenticate with an API key of the **Indexing** class that carries the
`index:write` scope; add `index:status` to track ingestion and `index:delete`
to remove documents or replace a whole datasource. Create one under **Workspace settings > API keys**; the
raw key starts with `nv_eu_idx_` and is shown once. See
[Authentication](/docs/guides/authentication). Each request also names your
workspace id as `tenantId`, the id in your workspace's address in the app
(`/w/<workspace id>/...`), and it must be the workspace the key belongs to.

## Push one document [#push-one-document]

`/documents/push` creates the document, or updates it when a document with the
same `id` already exists in the datasource.

```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` is your stable id for the document within the datasource. Pushing the
  same `id` again updates it; unchanged content is recognised by its hash and
  not indexed twice.
- `body.mimeType` is one of `text/plain`, `text/markdown`, `text/html`,
  `application/pdf`, or the Word, Excel and PowerPoint (`.docx`, `.xlsx`,
  `.pptx`) types. Binary content is sent base64-encoded.
- `sourceUrl` becomes the "jump to source" link on every citation of the
  document. Omit it on a re-push to keep the stored one, or send `null` to
  clear it.
- `type` sets the document's `content_type`, which search and list filter on.

The whole request body is capped at 1 MB, so a large file or a big batch
answers `413`; split it.

## Choose who can read it [#choose-who-can-read-it]

`permissions` is required on every push, so a sharing decision is never made
by leaving a field out. In a datasource visible to the workspace:

| `permissions` | Who can read the document |
| --- | --- |
| `{}` | Every member of the workspace |
| `{ "allowedUsers": ["ana@example.com"] }` | Only the people listed |
| `{ "allowedGroups": ["GROUP_ID"] }` | Members of those workspace groups, including nested groups |
| `{ "allowAllTenantMembers": false }` | Refused: a document nobody can read is a delete |

To change who can read a document without sending its content again, use
`POST /documents/push/permissions`. Making an already-restricted document
visible to the whole workspace additionally needs the `index:acl-widen` scope,
so a routine sync cannot quietly undo a restriction someone set by hand.

## Push in batches [#push-in-batches]

`/documents/push/bulk` takes up to 100 documents for one datasource per call.
The answer counts `accepted` and `rejected` and gives a result per document, so
one bad document does not fail the batch. The 1 MB body cap applies per call,
so split large uploads into several calls under the same `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": {} }
    ]
  }'
```

## Replace a whole datasource [#replace-a-whole-datasource]

When your system can list everything a datasource should hold, send the full
listing as one **upload session**, and the documents it no longer contains are
moved to the trash when the session closes. Sessions need an indexing API key
holding `index:delete` as well as `index:write`, because the close removes
documents; the key that opens one is the only key that can continue it.

1. Send the first page with `"isFirstPage": true`. It is page `0`.
2. Send every further page with its `pageIndex` (`1`, `2`, ...), in any order.
   A page sent twice counts once, so a retry is always safe.
3. Send the last page with `"isLastPage": true` and its `pageIndex`. A listing
   that fits in one page sends `isFirstPage` and `isLastPage` together. The
   last page may carry no documents.

Every page uses the same `uploadId`, and each answer carries the session's
progress under `upload`. The session closes only when every page from `0` to
the last has arrived. Closing it moves to the trash each document in the
datasource that no page of the session named and that existed before the
session opened. Any other push to the datasource while the session runs keeps
the document it names: a single push, a batch without session fields, a
permissions update, and a re-push of unchanged content alike. The trash keeps
what the close moved there for 30 days; pushing a document again brings it
back, and so does restoring the whole session (see below).

A session that receives no page for 24 hours expires and closes without
removing anything. A refused page is answered with `409 Conflict`, writes
nothing, and its `data.reason` says why:

| `reason` | What to do |
|---|---|
| `upload_incomplete` | Send the pages listed in `missingPageIndexes`, then the last page again |
| `deletion_confirmation_required` | The close would trash more than 20% of the datasource. If that is right, send the last page again with `"confirmDeletions"` set to `wouldTombstone` |
| `deletion_confirmation_too_large` | `confirmDeletions` is larger than the number of documents the datasource held when the session opened. Send the count you expect to remove |
| `upload_in_progress` | A session is open on this datasource. If it is your key's, finish it, wait for it to expire, or start over with `"forceRestartUpload": true` on your first page. If another key opened it, `forceRestartUpload` replaces it only once it has received no page for an hour, from the time in `restartableAt` |
| `upload_expired`, `upload_missing`, `upload_restarted` | The session is gone; start a new one with a new `uploadId` |
| `upload_closed`, `upload_id_reused` | The `uploadId` is spent; use a new one |
| `page_index_required` | Your key has a session open on this datasource; send `pageIndex` with the page |

To resume after a crash, read the session with
`GET /documents/push/upload?tenantId=...&datasource=...&uploadId=...` (scope
`index:status`). Its `missingPageIndexes` lists the pages still to send.

### Undo a session's close [#undo-a-sessions-close]

If a session removed documents it should not have, for example because the
listing it sent was cut short, restore them in one call:

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

The key that opened the session can restore it, and so can a workspace admin
signed in to Nordvec, for a session opened by any key. Every document the close
moved to the trash comes back with the content it had, and the answer counts
them: `restored` are live again, `purged` had already been deleted for good by
the trash, and `skipped` had changed since the close (pushed again, or removed
again) and were left as they are. Restoring a session twice answers with the
first restore's counts and `"replayed": true`, and queues any restored document
still waiting to be indexed, so repeating a restore that failed to answer is
safe. A session can be restored for 35 days after it closed, and for as long
as the trash still holds any document it removed. A refused restore is answered
with `409 Conflict` and its `data.reason`:

| `reason` | What it means |
|---|---|
| `upload_not_closed` | The session never closed, so it removed nothing |
| `upload_in_progress` | A session is open on the datasource. Restore once it has closed or expired |
| `restore_purged` | More than 30 days have passed, and the trash has deleted every one of the documents. Push them again |
| `workspace_not_entitled` | The workspace's plan does not currently allow restoring from the trash |
| `corpus_cap_exceeded` | Bringing the documents back would pass the workspace's document limit, so none came back. `data.wouldRestore` is how many it needs and `data.headroom` how many fit. Free room, then restore again |

## Track ingestion [#track-ingestion]

A push answers as soon as the document is queued. Ask for its progress with
`GET /documents/push/status` (scope `index:status`), filtered by datasource or
document id. A document moves from `queued` through `processing` to
`completed`, or to `failed` with an `error`.

## When a push is refused [#when-a-push-is-refused]

A push that names an unknown or paused datasource is answered with
`422 Unprocessable Content`. The message names the slug and links to
**Workspace settings > Datasources** in your workspace, and the error's `data`
says why and what to do:

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

Do not retry these automatically: they succeed only after an admin creates or
resumes the datasource.

## Remove a document [#remove-a-document]

`POST /documents/push/delete` (scope `index:delete`) removes a pushed document
by its `datasource` and `id`. Documents you stop pushing are not removed on
their own: delete each one you retire, or send the datasource's full listing as
an upload session, described above.

## Pause, resume and delete [#pause-resume-and-delete]

- **Pause** refuses every further push into the datasource. Its documents stay
  searchable. A push already being written when you pause completes.
- **Resume** accepts pushes again.
- **Delete** removes the datasource and every document pushed to it, with
  their search index. Your own system keeps its copy, so pushing again after
  you recreate the datasource restores them. A delete cannot be undone.

If another admin changed the datasource after your list loaded, the action is
refused and the list reloads, so you decide again against what is there now.
Every create, pause, resume and delete is recorded in the workspace audit log.

<Callout>
The settings list shows who each datasource is visible to. Who can read a
pushed document is decided by the `permissions` sent with it; creating,
pausing or deleting a datasource never widens access to anything.
</Callout>

<Callout>
Push writes are idempotent: repeat the same `Idempotency-Key` on every retry of
one write, and a duplicate is answered from the first attempt instead of being
applied twice. See [Errors and rate limits](/docs/guides/errors-and-rate-limits).
</Callout>

## Next steps [#next-steps]

<Cards>
  <Card title="List and retrieve documents" href="/docs/guides/how-to/list-documents" />
  <Card title="Filter and refine search" href="/docs/guides/how-to/filter-search" />
  <Card title="API reference" href="/docs/api" />
</Cards>


---

# Connectors
Source: https://nordvec.com/docs/guides/connectors

Every source Nordvec can import, from cloud storage and email to CRMs and accounting, stored in the EU and private to the person who connected it until they share it.

Nordvec has 17 connectors you can connect and 11 planned.
Each connector's page covers what it imports and how to filter searches by it.
Which connectors can be connected right now is published live, with the full
list, at [`/docs/connectors.json`](/docs/connectors.json).

<Callout>
Everything a connector imports is stored and searched in the EU.
Documents from a connector are private to the person who connected it until that person shares them.
</Callout>

### Cloud storage [#cloud-storage]

<Cards>
  <Card title="Box" href="/docs/guides/connectors/box" />
  <Card title="Dropbox" href="/docs/guides/connectors/dropbox" />
  <Card title="Google" href="/docs/guides/connectors/google" />
  <Card title="Microsoft" href="/docs/guides/connectors/microsoft" />
</Cards>

### Communication [#communication]

<Cards>
  <Card title="Slack" href="/docs/guides/connectors/slack" />
</Cards>

### CRM [#crm]

<Cards>
  <Card title="HubSpot" href="/docs/guides/connectors/hubspot" />
  <Card title="Pipedrive" href="/docs/guides/connectors/pipedrive" />
  <Card title="Salesforce (Planned)" href="/docs/guides/connectors/salesforce" />
</Cards>

### Customer support [#customer-support]

<Cards>
  <Card title="Freshdesk" href="/docs/guides/connectors/freshdesk" />
  <Card title="Intercom (Planned)" href="/docs/guides/connectors/intercom" />
  <Card title="Zendesk (Planned)" href="/docs/guides/connectors/zendesk" />
</Cards>

### Developer tools [#developer-tools]

<Cards>
  <Card title="GitHub" href="/docs/guides/connectors/github" />
  <Card title="Linear" href="/docs/guides/connectors/linear" />
</Cards>

### Knowledge bases [#knowledge-bases]

<Cards>
  <Card title="Confluence" href="/docs/guides/connectors/confluence" />
  <Card title="Notion" href="/docs/guides/connectors/notion" />
  <Card title="Guru (Planned)" href="/docs/guides/connectors/guru" />
</Cards>

### Project management [#project-management]

<Cards>
  <Card title="Asana" href="/docs/guides/connectors/asana" />
  <Card title="ClickUp" href="/docs/guides/connectors/clickup" />
  <Card title="Jira" href="/docs/guides/connectors/jira" />
  <Card title="Monday.com" href="/docs/guides/connectors/monday" />
  <Card title="Trello" href="/docs/guides/connectors/trello" />
</Cards>

### Accounting [#accounting]

<Cards>
  <Card title="Dinero (Planned)" href="/docs/guides/connectors/dinero" />
  <Card title="e-conomic (Planned)" href="/docs/guides/connectors/economic" />
  <Card title="Fortnox (Planned)" href="/docs/guides/connectors/fortnox" />
  <Card title="QuickBooks (Planned)" href="/docs/guides/connectors/quickbooks" />
  <Card title="Visma (Planned)" href="/docs/guides/connectors/visma" />
  <Card title="Xero (Planned)" href="/docs/guides/connectors/xero" />
</Cards>

### Meetings [#meetings]

<Cards>
  <Card title="Zoom (Planned)" href="/docs/guides/connectors/zoom" />
</Cards>