Documents and search

This part of the API manages document content and the search layer that grounded answers depend on.

How it works

Document create and update are asynchronous. The API accepts the request first and processes the content in the background.

Examples below call the hosted EU API (https://api.radioso.ai); swap in https://api-us.radioso.ai, or your own origin such as http://localhost:8080, to match wherever your workspace token was issued — see Workspaces and tokens.

Create a document from inline text

curl -sS -X POST https://api.radioso.ai/api/v1/document/ \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"title":"FAQ","content":"Radioso can answer questions grounded in uploaded content.","metadata":{"category":"support"},"externalDocumentId":"faq-001"}'

title and content are required. metadata and externalDocumentId are optional.

Import a file

Use multipart import when you want Radioso to extract text from an uploaded source file. Imports accept PDF, Markdown (.md / .markdown), plain text, DOCX, and XLSX files.

curl -sS -X POST https://api.radioso.ai/api/v1/document/import \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -F "file=@./handbook.pdf" \
  -F "title=Support handbook"

The TypeScript SDK wraps the same multipart route:

import { readFile } from 'node:fs/promises'
import { createRadiosoClient } from '@radioso/typescript-sdk'
 
const client = createRadiosoClient({
  apiToken: process.env.RADIOSO_API_TOKEN!,
})
 
const file = await readFile('./handbook.pdf')
 
await client.documents.importFile({
  file,
  filename: 'handbook.pdf',
  title: 'Support handbook',
  mimeType: 'application/pdf',
})

The backend enforces a maximum upload size with DOCUMENT_UPLOAD_MAX_BYTES. The upload path is also rate-limited separately from normal auth flows.

Update or reprocess a document

Use PUT /api/v1/document/{documentId} when the content changed.

Use POST /api/v1/document/{documentId}/reprocess when you want to run the current stored content through the latest processing path again.

Both flows return 202 because processing is queued.

Document detail responses include extraction provenance when a processing run attempted or skipped metadata extraction. The enrichment object reports safe operator fields such as status, detected shape, model, anchor date, fact count, applied chunk count, and failure reason. It does not include source text, prompts, completions, or chunk content.

Document creation (POST /api/v1/document/) and file import (POST /api/v1/document/import) accept the same optional documentEnrichmentOverride field ("on" or "off"), which applies to the processing run that the request queues.

Single-document reprocess accepts an optional metadata extraction override for that run:

curl -sS -X POST https://api.radioso.ai/api/v1/document/document-id/reprocess \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documentEnrichmentOverride":"on"}'

documentEnrichmentOverride can be on or off. It is stored on the processing job, not on the queue message, and it does not change the saved workspace or source setting.

Source metadata extraction and reprocessing

Sources expose documentEnrichmentOverride as inherit, on, or off. inherit uses the workspace ingestion setting.

Update a source override:

curl -sS -X PATCH https://api.radioso.ai/api/v1/document/sources/source-id \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documentEnrichmentOverride":"on"}'

Reprocess only one source:

curl -sS -X POST https://api.radioso.ai/api/v1/document/sources/source-id/reprocess \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"documentEnrichmentOverride":"on"}'

The response reports queuedDocumentCount, skippedDocumentCount, and a status of queued or noop. Documents already queued or processing are skipped rather than duplicated.

Search documents

curl -sS -X POST https://api.radioso.ai/api/v1/document/search \
  -H "Authorization: Bearer $RADIOSO_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"uploaded content","metadataFilter":{"category":"support"}}'

query is required. metadataFilter is optional.

Search history

Use GET /api/v1/document/search/history to list previous searches.

Use GET /api/v1/document/search/history/{searchId} to replay one historical search result set.

In practice, this is useful when you are tuning retrieval and want to compare current behavior with a known past search.

Endpoint reference

Field-level detail for document, source, and search bodies is in the API Reference.

GET    /api/v1/document/
POST   /api/v1/document/
POST   /api/v1/document/import
GET    /api/v1/document/{documentId}
PUT    /api/v1/document/{documentId}
DELETE /api/v1/document/{documentId}
POST   /api/v1/document/{documentId}/reprocess
GET    /api/v1/document/sources
GET    /api/v1/document/sources/{sourceId}/documents
PATCH  /api/v1/document/sources/{sourceId}
POST   /api/v1/document/sources/{sourceId}/reprocess
POST   /api/v1/document/sources/{sourceId}/recrawl
POST   /api/v1/document/sources/{sourceId}/pause-crawl
POST   /api/v1/document/sources/{sourceId}/resume-crawl
DELETE /api/v1/document/sources/{sourceId}
POST   /api/v1/document/search
GET    /api/v1/document/search/history
GET    /api/v1/document/search/history/{searchId}

Common failure modes

• 400 usually means a required field is missing or the search body is invalid.
• 401 means the workspace token is missing or invalid.
• 404 means the document or search id does not exist in the current workspace context.

Read next

• Chat and history
• Settings
• API Reference