Skip to main content
POST
/
retrieve
curl --request POST \
  --url https://api-prod.voltai.ai/source/api/retrieve/ \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '
{
  "keyword": "GPIO interrupt mask",
  "search_mode": "keyword",
  "topk": 10
}
'
{
  "chunks": [
    {
      "filename": "<string>",
      "page": 123,
      "llm_context": "<string>",
      "bbox": "<array>",
      "score": 123,
      "chunk_id": "<string>"
    }
  ]
}

Documentation Index

Fetch the complete documentation index at: https://docs.voltai.ai/llms.txt

Use this file to discover all available pages before exploring further.

Use POST /retrieve/ to run keyword (full-text) or semantic (vector) search over your organization’s indexed documents and return up to topk chunks. Results include the chunk text (llm_context), source filename, page reference, layout bbox, relevance score, and chunk_id. Send your API key in the X-API-KEY header. Base URL is typically https://api-prod.voltai.ai/source/api.

​
API key scope

This endpoint requires the retrieval permission on your API key when the key uses granular scopes (allowed_permissions in the admin). Keys with empty allowed_permissions keep full access (including retrieval). Keys scoped only to sources. must also include retrieval to call this route.

​
Request body

  • keyword (required) — Search string. Use document terms for keyword mode; short phrases or questions work well for semantic mode.
  • search_mode (required) — keyword or semantic.
    • keyword — Elasticsearch full-text search over indexed chunk text.
    • semantic — Vector similarity search (Milvus) over embeddings.
  • topk (optional) — Maximum chunks to return; default 10, max 100.

​
Response

  • chunks — Array of objects, each with:
    • filename — Source name.
    • page — Page number or list of pages, depending on how the chunk was split.
    • llm_context — Text content of the chunk.
    • bbox — Bounding box(es) for the region (format depends on source type).
    • score — Backend relevance score (may be null in edge cases).
    • chunk_id — Stable chunk identifier in the org’s chunk store.
Chunks are sorted by descending relevance score when a score is present.

​
Errors

  • 400 — Invalid input (for example empty keyword after trimming, or invalid search_mode).
  • 403 — Missing/invalid API key, or key lacks the retrieval scope.

​
Example request

Set environment variable API_KEY to your key (same as for other Source API calls), then: 
curl -s -X POST "https://api-prod.voltai.ai/source/api/retrieve/" \
  -H "X-API-KEY: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"keyword":"EMC radiated emissions","search_mode":"keyword","topk":8}'

​
Example response

{
  "chunks": [
    {
      "filename": "emc-guide.pdf",
      "page": 14,
      "llm_context": "Radiated emissions shall be measured at 3 m with a biconical antenna...",
      "bbox": [[72.0, 120.5, 540.0, 200.0]],
      "score": 0.91,
      "chunk_id": "abc123..."
    }
  ]
}
See also the basic operations guide for sources workflows before searching.

Authorizations

​
X-API-KEY
string
header
required

API key from organization settings. Must include the retrieval scope when the key uses granular permissions.

Body

application/json
​
keyword
string
required

Search text. For keyword mode, use terms that appear in the documents; for semantic mode, short phrases or questions work well.

​
search_mode
enum<string>
required

keyword — full-text search on indexed text. semantic — dense vector similarity search.

Available options:
keyword,
semantic
​
topk
integer
default:10

Maximum number of texts to return.

Required range: 1 <= x <= 100
​
topic_uuid
string<uuid> | null

If set, restricts results to sources linked to this topic (including its subtree). Omit to search across all sources the key may access.

Response

Ranked texts (may be empty if nothing matches).

​
chunks
object[]
required