# Context pack: Core concepts
Source: https://nordvec.com/cs/docs/guides/concepts
Pack: https://nordvec.com/cs/docs/packs/concepts
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. [Core concepts](https://nordvec.com/cs/docs/guides/concepts) (this guide)
2. [Documents & search](https://nordvec.com/cs/docs/guides/concepts/documents) (linked from this guide)
3. [Conversations & citations](https://nordvec.com/cs/docs/guides/concepts/conversations) (linked from this guide)
---
# Core concepts
Source: https://nordvec.com/cs/docs/guides/concepts
The two things everything in Nordvec is built on, documents you can search and conversations that cite them.
Every connector, push and search in Nordvec produces or reads a document, and
every answer the assistant gives is a conversation grounded in those documents.
Start here to learn what each one holds and who can see it.
- [Documents & search](https://nordvec.com/cs/docs/guides/concepts/documents): Documents are the searchable unit in Nordvec. Ingest them, then find them with full-text search over the API.
- [Conversations & citations](https://nordvec.com/cs/docs/guides/concepts/conversations): A conversation is a chat grounded in your documents, where every answer is traced to its source.
---
# Documents & search
Source: https://nordvec.com/cs/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.
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.
Search only ever returns documents the caller is allowed to see. Access is
enforced in the database, not in application code.
## 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/cs/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.
Answers are generated by AI. Citations are what make them verifiable, not just
plausible.
## 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.