Skip to content

Semantic document search

POST
/v1/document/search
curl --request POST \
--url https://localhost:8080/v1/document/search \
--header 'Content-Type: application/json' \
--data '{ "query": "refund policy for annual plans" }'

Env-enzo sidecar API: served by the per-request env-enzo container, not by env-manager, so this path is never called directly. Reach it through the tunnel edge POST /v1/tunnels/{id}/edge/api/document/search (tunnel credentials), which proxies the body and this response verbatim.

Finds the chunks of the request’s indexed documents that are semantically closest to query, ranked by embedding similarity. Only available when the enclave was provisioned with an AI pipeline (document datasources); otherwise it answers 503.

Natural-language search text

Media typeapplication/json
object
query
required

Query is the natural-language text to search the request’s indexed documents for. Matched by embedding similarity, not keyword.

string

Example

refund policy for annual plans

Matching chunks, best match first

Media typeapplication/json
object
results

Results are the matching chunks, best match first. Empty when nothing matched.

Array<object>
object
content

Content is the text of the matched document chunk.

string
location

Location identifies the source document: an s3:// URI for object-store sources, a file path for local sources, or “unknown”.

string
metadata

Metadata is the raw metadata stored with the chunk by the indexer (source, path, bucket, key, distance, …). Keys depend on the source type.

object
key
additional properties
similarity

Similarity is the cosine similarity between the query and the chunk, in [0,1]; higher is closer. Results are returned in the order the index ranked them.

number

Example

{
"results": [
{
"content": "Annual plans can be refunded within 30 days of purchase.",
"location": "s3://acme-policies/refunds.pdf",
"similarity": 0.87
}
]
}

Missing or empty query

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

Rate limit exceeded

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

Search failed

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}

No AI pipeline configured for this enclave

Media typeapplication/json
object
error

Error is a human-readable message. For 400 it is either the validation failure (“sql field is required and cannot be empty”, “write operations are not allowed”) or DuckDB’s own parser/binder/catalog message so the SQL can be fixed; for 409 the datasets are still loading and the query should be retried shortly.

string

Example

{
"error": "Binder Error: Referenced column \"emial\" not found in FROM clause!"
}