Document upload
Everything grounded starts here. Whatever you upload is the evidence your agent answers from, so if the wrong content goes in, or processing never finishes, no later stage of retrieval can rescue the answer. Getting upload right does more for answer quality than any other single step.
Two ingestion paths
- Inline text ingestion: create a document from title, content, optional metadata, and optional external id.
- File import: upload a file and let Radioso extract source content before chunking.
Inline documents can also carry a source. For website-backed content, pass source: { kind: "website", url: "https://example.com/docs" }. Radioso creates or reuses a source inside the current workspace and links the document to it.
What happens after upload
Upload doesn’t finish the job; it starts a background pipeline. Here’s the sequence.
The API accepts the document
The document is created or updated and the API responds with 202 Accepted.
Processing is queued
Document work moves to the background worker instead of being completed inline.
Source content is normalized
Uploaded files are parsed into markdown or text content. Inline text documents already have their source content.
Chunks and embeddings are generated
The worker applies workspace ingestion settings, creates searchable chunks, and generates embeddings.
Optional metadata extraction runs
When metadata extraction is enabled for the workspace, source, or reprocess run, the worker understands the document type and may add date tags to dated event chunks.
Retrieval can use the document
Grounded answers can cite a document only after its processing completes.
You can follow all of this in the Documents list: a document reads Ready once its latest revision has finished processing, and retrieval can use it from that moment on.
What to verify after import
- the document exists in the workspace
- processing finished successfully for the latest revision
- the document metadata looks correct
- extraction provenance looks correct if metadata extraction was enabled
- at least one grounded query retrieves it when asked directly about the document
Metadata and external ids
If you plan to filter or bias retrieval later, add metadata at ingestion time. Metadata becomes part of document and chunk search behavior, and metadata rules and direct metadata filters can act on it.
externalDocumentId earns its keep when Radioso mirrors documents that already live in another system and you need a stable reference for sync or reconciliation. When a document has a source, the external id is scoped to that workspace source.
Common failure pattern
The most common mistake is testing chat the moment upload returns and reading a weak answer as broken retrieval. More often the document hasn’t finished processing.
Treat document status as part of the ingestion contract. Upload success and retrieval readiness are not the same event.