# Ingestion overview (https://brainapi.lumen-labs.ai/docs/v2/ingestion)

> For the complete BrainAPI documentation index, see [llms.txt](https://brainapi.lumen-labs.ai/docs/llms.txt). A markdown version of any docs page is available by appending `.md` to its URL (e.g. https://brainapi.lumen-labs.ai/docs/v2/ingestion.md).

Choose the smallest ingestion path that preserves the knowledge your application needs

Ingestion turns source material into representations that later retrieval surfaces can use. Choose the path from the structure you already have, not from the retrieval feature you hope to use.

## Choose an input path

| Input | Endpoint | Choose it when |
| --- | --- | --- |
| Plain text or pre-extracted Markdown | `POST /ingest/` | Language contains the facts and relationships to discover. |
| PDF, document, or other uploaded file | `POST /ingest/file` | BrainAPI or a configured parser must extract text first. |
| Known triples or events | `POST /ingest/structured` | Your application already knows subjects, predicates, objects, IDs, or timestamps. |
| Search-only passages | `POST /ingest/` with `skip_enrichment=true` | You need ranked passage retrieval without graph enrichment. |

## Choose a structured mode

| Mode | Behavior | Typical use |
| --- | --- | --- |
| `deterministic` | Writes supported structure without LLM enrichment. | Imports, catalog attributes, preferences, controlled events. |
| `hybrid` | Preserves supplied structure and fills supported missing information. | Partially structured application events. |
| `enrich` | Uses the enrichment path for the supplied data. | Inputs where additional semantic detail is worth model cost. |

If `mode` is omitted, BrainAPI infers a safe path from the payload. `skip_enrichment=true` prevents enrichment and is useful when supplied facts must remain literal.

## Direct edges or event hubs

Use a direct `subject → predicate → object` triple for static facts such as `HAS`, membership, or `PREFERS`. Add `event` and `event_obj` together when an action needs a first-class event with time or context. Sending only one member of the pair is invalid.

## Understand task completion

Text and structured endpoints return `202` and a `task_id`. Poll the same brain through `/tasks/{task_id}`. Do not query immediately and assume missing data means ingestion failed.

## Prepare for retrieval

- Context can use graph and passage representations.
- Search requires PostgreSQL and `SEARCH_ENABLED=true`; lexical indexes are populated during compatible ingestion.
- Catalog personalization requires passages mapped to stable graph `node_id` values.
- Recommendations require a target node and useful relationships or interactions.

## Continue

- [Save text](https://brainapi.lumen-labs.ai/docs/v2/ingestion/text)
- [Save files](https://brainapi.lumen-labs.ai/docs/v2/ingestion/files)
- [Save structured data](https://brainapi.lumen-labs.ai/docs/v2/ingestion/structured-data)
- [Track ingestion tasks](https://brainapi.lumen-labs.ai/docs/v2/ingestion/tasks)
- [Choose a retrieval surface](https://brainapi.lumen-labs.ai/docs/v2/retrieval)