HTTP API
Search documents
const url = 'https://sergo.example.com/v1/search';const options = { method: 'POST', headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'}, body: '{"query":"example","limit":10,"offset":0,"filter":{"folder_ids":[],"document_ids":[]}}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url https://sergo.example.com/v1/search \ --header 'Authorization: Bearer <token>' \ --header 'Content-Type: application/json' \ --data '{ "query": "example", "limit": 10, "offset": 0, "filter": { "folder_ids": [], "document_ids": [] } }'Searches the text of the documents the key can read, and the file names. Returns the best passage of each document, best first, with up to 3 more passages of the same document. Each passage has its page, and its section heading in Word files. next_offset says where the next page starts when there are more.
Only processed documents are searched — see indexed on a document.
Authorizations
Section titled “Authorizations”Request Bodyrequired
Section titled “Request Bodyrequired”object
What to look for — plain words or a question
How many documents to return, up to 50
Skip this many documents — next_offset from the last response gives the next page
Narrow the search. It can’t reach past what the key can read
object
Only these folders, and the folders inside them
Only these documents
Responses
Section titled “Responses”Successful Response
object
One per document, best first
object
object
Its folder, starting with the owner’s name: Ava Bennett's documents/Handbook
The id of this document’s best passage
Its page may hold a figure, chart or table that the text misses
page is an estimate, for a file without pages of its own
score sets the order — only the order matters, not the number. lexical_rank and dense_rank are its place by keywords and by meaning, when it was found that way. Other keys depend on the index
object
Up to 3 more passages of the same document that ranked, best first
object
Its page may hold a figure, chart or table that the text misses
page is an estimate, for a file without pages of its own
score sets the order — only the order matters, not the number. lexical_rank and dense_rank are its place by keywords and by meaning, when it was found that way. Other keys depend on the index
object
What the search did, for people to read
object
filter_outside_scope: the filter names nothing the caller can read, so nothing was searched
How it searched: by keywords, and by meaning when the install has an embedding model
Example
{ "modes": [ "lexical" ], "results": [ { "chunk_id": "9fHc2RxN", "document": { "folder_path": "Ava Bennett's documents/Handbook", "id": "4kTq8Wmz", "name": "Leave policy.pdf" }, "page": 4, "page_estimated": false, "passages": [ { "chunk_id": "Bv7Lq3Ps", "page": 5, "page_estimated": false, "quote": "Table 2 shows the carry-over limits by grade.", "scores": { "lexical_rank": 3, "score": 0.61 }, "view": true } ], "quote": "Unused annual leave carries over to the next year, up to five days.", "scores": { "lexical_rank": 1, "score": 0.94 }, "view": false } ], "steps": [ { "detail": "key scope — 2 folders (including children)", "name": "Scope" }, { "detail": "default (postgres)", "name": "Index" }, { "detail": "12 passages by keywords", "name": "Matched" } ], "warnings": []}Validation Error
object
What was wrong, field by field
Example
{ "code": "invalid_request"}