Ingesting documents

Uploading a document is fast and asynchronous: the file is stored immediately, then indexed in the background. You poll for readiness before querying.

1. Upload a file

POST the file as multipart/form-data with a file field to a collection you own. Accepted types are PDF, plain text, and Markdown (≤ 25 MB). The response is the new document at status uploaded.

curl -X POST 'https://rag.lucasfurtado.xyz/api/v1/collections/col_9f8b2a1c/documents' \
  -H 'Authorization: Bearer rag_live_YOUR_KEY' \
  -F 'file=@./handbook.pdf'

2. Poll for status

Ingestion (parse → chunk → embed → index) runs asynchronously. Poll the lightweight status endpoint until the document is ready (or error):

curl 'https://rag.lucasfurtado.xyz/api/v1/documents/doc_4c1e77a0/status' \
  -H 'Authorization: Bearer rag_live_YOUR_KEY'

{ "status": "ready", "chunkCount": 42, "updatedAt": 1753800000000 }

3. The lifecycle

A document moves through these states:

Status	Meaning
`uploaded`	Stored and queued; indexing has not started.
`processing`	Being parsed, chunked, embedded, and indexed.
`ready`	Indexed and queryable. `chunkCount` is populated.
`error`	Ingestion failed; `error` explains why. Fix the source and re-ingest.

A collection must have at least one ready document before it can be queried — querying an empty collection returns 409.

Re-ingesting

If a document errored, or you want to re-index it, trigger a re-run. It is safe to repeat — vector ids are deterministic, so a re-run overwrites rather than duplicates:

curl -X POST 'https://rag.lucasfurtado.xyz/api/v1/documents/doc_4c1e77a0/reingest' \
  -H 'Authorization: Bearer rag_live_YOUR_KEY'

Once a document is ready, head to the reference and try the query endpoint.