> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ndi.nace.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# File lifecycle

> Upload, ingest, search, replace, and retain

A workspace file is not searchable when it lands. Ingestion builds the derived
representations (index, metadata catalog, optional knowledge graph).

```mermaid theme={"dark"}
flowchart LR
  upload[Upload or session] --> ledger[Ledger row]
  ledger --> ingest[Ingest]
  ingest --> index[Search index]
  ingest --> catalog[Metadata catalog]
  ingest --> kg[Knowledge graph optional]
  index --> tools[Tools and search]
  catalog --> filtered[Filtered search]
  kg --> kgTools[KG tools]
```

## States you will see

* **Uploaded, not ingested** — `list_files` shows the row; hybrid search, QA, and filtered search will miss it or report it as not ingested.
* **Ingested** — tools can read it. `workspaces.stats` reports counts by ingestion status.
* **Stale** — the source bytes or labels changed after the last ingest. Call `ingestion.ingest(..., stale_only=True)` or `reconcile`.
* **Replaced** — `files.replace` or `on_conflict=new_version` writes a new version and retires prior derived outputs.
* **Deleted** — the ledger row is gone; derived material is torn down with it.

## Retention

Workspace `retention_policy` sets TTLs for:

* **derived** material (anchored on `ingested_at`)
* **source** bytes (anchored on `created_at`)
* **job** payloads (default 30 days; `null` keeps them forever)

When a job result expires, `GET /v1/jobs/{id}` still exists but `result` is gone and reads raise `result_expired`.

Granular `POST /v1/uploads` handles are separate: 24-hour default TTL, 7-day cap, deleted when the consuming job finishes. See [Sources and uploads](/concepts/sources-and-uploads).