Search records
curl --request POST \
--url https://api.example.com/v0/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"corpus_ids": [
"<string>"
],
"mode": "hybrid",
"profile": "default",
"limit": 10,
"evaluation_plugin": "<string>",
"evaluation_space": "<string>",
"filter": {
"source_namespaces": [
"<string>"
],
"record_ids": [
"<string>"
],
"version_ids": [
"<string>"
],
"metadata": [
{
"field": "<string>",
"any_of": [
"<string>"
],
"gte": "2023-11-07T05:31:56Z",
"lte": "2023-11-07T05:31:56Z"
}
]
}
}
'import requests
url = "https://api.example.com/v0/search"
payload = {
"query": "<string>",
"corpus_ids": ["<string>"],
"mode": "hybrid",
"profile": "default",
"limit": 10,
"evaluation_plugin": "<string>",
"evaluation_space": "<string>",
"filter": {
"source_namespaces": ["<string>"],
"record_ids": ["<string>"],
"version_ids": ["<string>"],
"metadata": [
{
"field": "<string>",
"any_of": ["<string>"],
"gte": "2023-11-07T05:31:56Z",
"lte": "2023-11-07T05:31:56Z"
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
corpus_ids: ['<string>'],
mode: 'hybrid',
profile: 'default',
limit: 10,
evaluation_plugin: '<string>',
evaluation_space: '<string>',
filter: {
source_namespaces: ['<string>'],
record_ids: ['<string>'],
version_ids: ['<string>'],
metadata: [
{
field: '<string>',
any_of: ['<string>'],
gte: '2023-11-07T05:31:56Z',
lte: '2023-11-07T05:31:56Z'
}
]
}
})
};
fetch('https://api.example.com/v0/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'corpus_ids' => [
'<string>'
],
'mode' => 'hybrid',
'profile' => 'default',
'limit' => 10,
'evaluation_plugin' => '<string>',
'evaluation_space' => '<string>',
'filter' => [
'source_namespaces' => [
'<string>'
],
'record_ids' => [
'<string>'
],
'version_ids' => [
'<string>'
],
'metadata' => [
[
'field' => '<string>',
'any_of' => [
'<string>'
],
'gte' => '2023-11-07T05:31:56Z',
'lte' => '2023-11-07T05:31:56Z'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"record_id": "<string>",
"version_id": "<string>",
"part_key": "<string>",
"segment_id": "<string>",
"segmentation_id": "<string>",
"projection_generation_id": "<string>",
"rank": 2,
"excerpt": {
"text": "<string>",
"start": 1,
"end": 1,
"coordinate_system": "unicode_codepoint"
},
"availability": {
"state": "materialized",
"is_current": true,
"searchable": true
},
"embedding_artifact_id": "<string>",
"vector_space_id": "<string>",
"passage_text": "<string>",
"source_excerpts": [
{
"part_key": "<string>",
"text": "<string>",
"start": 1,
"end": 1,
"coordinate_system": "unicode_codepoint"
}
],
"explanation": "<string>"
}
],
"retrieval_profile": {
"name": "<string>",
"version": "<string>",
"degraded": [
{
"reason": "vectors_unavailable",
"corpus_ids": [
"<string>"
]
}
]
},
"excluded_corpora": [
{
"corpus_id": "<string>",
"fields": [
"<string>"
]
}
],
"usage": {
"rounds": 2,
"elapsed_ms": 1,
"paid_calls": 1,
"cost_cents": 1,
"profiles": [
{
"profile": "<string>",
"plugin_version": "<string>",
"rounds": 2,
"paid_calls": 1,
"cost_cents": 1
}
],
"phases": {
"routing_ms": 1,
"coverage_ms": 1,
"plugin_rounds_ms": 1,
"query_encoding_ms": 1,
"index_query_ms": 1,
"hydration_ms": 1
}
}
}{
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"trace_id": "<string>",
"span_id": "<string>",
"field": "<string>",
"resync_url": "<string>"
}Search
Search records
Resolve the requested profile, compile mandatory Corpus/Organization prefilters and any requested filter, obtain candidates, then canonically hydrate and reauthorize every returned segment. Lexical-first records remain eligible without embeddings; semantic-only queries require vector coverage. Ordinary hybrid searches use keywords for Corpora whose served vectors are unavailable, reporting their ids in retrieval_profile.degraded. Other Corpora keep their hybrid ranking. Explicit semantic requests remain 422 unsupported_search when vector search cannot run. Unknown coverage alone does not disable a routed space. Profile selection does not change access/currentness rules. When a retrieval plugin is pinned, it ranks. It asks the engine for candidates in up to three rounds and returns its ranking, which may hold only candidates the engine served in this search, each already authorized and hydrated. Each API process admits at most 64 active searches across callers. At capacity it immediately returns retryable 503 search_unavailable with Retry-After before storage or plugin work. A query encoding model that cannot answer returns retryable 503 model_unavailable, including the legacy inference service and the ingestion plugin that owns the requested vector space.
POST
/
v0
/
search
Search records
curl --request POST \
--url https://api.example.com/v0/search \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"query": "<string>",
"corpus_ids": [
"<string>"
],
"mode": "hybrid",
"profile": "default",
"limit": 10,
"evaluation_plugin": "<string>",
"evaluation_space": "<string>",
"filter": {
"source_namespaces": [
"<string>"
],
"record_ids": [
"<string>"
],
"version_ids": [
"<string>"
],
"metadata": [
{
"field": "<string>",
"any_of": [
"<string>"
],
"gte": "2023-11-07T05:31:56Z",
"lte": "2023-11-07T05:31:56Z"
}
]
}
}
'import requests
url = "https://api.example.com/v0/search"
payload = {
"query": "<string>",
"corpus_ids": ["<string>"],
"mode": "hybrid",
"profile": "default",
"limit": 10,
"evaluation_plugin": "<string>",
"evaluation_space": "<string>",
"filter": {
"source_namespaces": ["<string>"],
"record_ids": ["<string>"],
"version_ids": ["<string>"],
"metadata": [
{
"field": "<string>",
"any_of": ["<string>"],
"gte": "2023-11-07T05:31:56Z",
"lte": "2023-11-07T05:31:56Z"
}
]
}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
query: '<string>',
corpus_ids: ['<string>'],
mode: 'hybrid',
profile: 'default',
limit: 10,
evaluation_plugin: '<string>',
evaluation_space: '<string>',
filter: {
source_namespaces: ['<string>'],
record_ids: ['<string>'],
version_ids: ['<string>'],
metadata: [
{
field: '<string>',
any_of: ['<string>'],
gte: '2023-11-07T05:31:56Z',
lte: '2023-11-07T05:31:56Z'
}
]
}
})
};
fetch('https://api.example.com/v0/search', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/v0/search",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'query' => '<string>',
'corpus_ids' => [
'<string>'
],
'mode' => 'hybrid',
'profile' => 'default',
'limit' => 10,
'evaluation_plugin' => '<string>',
'evaluation_space' => '<string>',
'filter' => [
'source_namespaces' => [
'<string>'
],
'record_ids' => [
'<string>'
],
'version_ids' => [
'<string>'
],
'metadata' => [
[
'field' => '<string>',
'any_of' => [
'<string>'
],
'gte' => '2023-11-07T05:31:56Z',
'lte' => '2023-11-07T05:31:56Z'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/v0/search"
payload := strings.NewReader("{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/v0/search")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/v0/search")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"query\": \"<string>\",\n \"corpus_ids\": [\n \"<string>\"\n ],\n \"mode\": \"hybrid\",\n \"profile\": \"default\",\n \"limit\": 10,\n \"evaluation_plugin\": \"<string>\",\n \"evaluation_space\": \"<string>\",\n \"filter\": {\n \"source_namespaces\": [\n \"<string>\"\n ],\n \"record_ids\": [\n \"<string>\"\n ],\n \"version_ids\": [\n \"<string>\"\n ],\n \"metadata\": [\n {\n \"field\": \"<string>\",\n \"any_of\": [\n \"<string>\"\n ],\n \"gte\": \"2023-11-07T05:31:56Z\",\n \"lte\": \"2023-11-07T05:31:56Z\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"items": [
{
"record_id": "<string>",
"version_id": "<string>",
"part_key": "<string>",
"segment_id": "<string>",
"segmentation_id": "<string>",
"projection_generation_id": "<string>",
"rank": 2,
"excerpt": {
"text": "<string>",
"start": 1,
"end": 1,
"coordinate_system": "unicode_codepoint"
},
"availability": {
"state": "materialized",
"is_current": true,
"searchable": true
},
"embedding_artifact_id": "<string>",
"vector_space_id": "<string>",
"passage_text": "<string>",
"source_excerpts": [
{
"part_key": "<string>",
"text": "<string>",
"start": 1,
"end": 1,
"coordinate_system": "unicode_codepoint"
}
],
"explanation": "<string>"
}
],
"retrieval_profile": {
"name": "<string>",
"version": "<string>",
"degraded": [
{
"reason": "vectors_unavailable",
"corpus_ids": [
"<string>"
]
}
]
},
"excluded_corpora": [
{
"corpus_id": "<string>",
"fields": [
"<string>"
]
}
],
"usage": {
"rounds": 2,
"elapsed_ms": 1,
"paid_calls": 1,
"cost_cents": 1,
"profiles": [
{
"profile": "<string>",
"plugin_version": "<string>",
"rounds": 2,
"paid_calls": 1,
"cost_cents": 1
}
],
"phases": {
"routing_ms": 1,
"coverage_ms": 1,
"plugin_rounds_ms": 1,
"query_encoding_ms": 1,
"index_query_ms": 1,
"hydration_ms": 1
}
}
}{
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"trace_id": "<string>",
"span_id": "<string>",
"field": "<string>",
"resync_url": "<string>"
}Authorizations
Body
application/json
Text-only top-k query. Resolve all Corpora in the authenticated Organization and require read/search permission for every requested Corpus before querying. Never silently drop an unauthorized Corpus. Unknown/unsupported profile or mode returns 422; a dependency outage is an error, not an empty successful result. Query token limits are checked against the resolved profile; no silent truncation. An optional filter narrows candidates inside the engine query, before ranking and the limit, in every mode. The first-party retrieval plugin returns each Record once, with its best matching passage; custom plugins can request individual passages. Pagination is outside this surface.
At most 8192 code points on the wire. A semantic or hybrid query is also limited by the owner of the searched vector space (the first-party core.ingest plugin accepts at most 256 tokens of its model's tokenizer); a longer query is refused with 422 query_too_long, whose message names the limit, never truncated.
Required string length:
1 - 8192Candidate filter applied before ranking. Every present condition must hold. A requested Corpus served by a Projection Generation built before source filtering existed returns 422 source_filter_unavailable; rebuild that Corpus once (rebuildCorpusProjection) to enable it. Unfiltered search is unaffected.
Show child attributes
Show child attributes
Response
Successful response
Bounded top-k results after canonical rechecks. May contain fewer hits than requested; no total count, completeness promise or stable pagination snapshot. Empty results still name the resolved profile.