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

​
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.