Search
Returns the passages that answer a question, best first, from one or more drives.
Scope: Search. Operation name: search. Guide: Search.
Body
The question, in plain language. At most 2,048 characters.
One or more drives the key reaches. If you pass several, the response is a single ranked list across them.
How much work the search does. There's no default; medium suits most questions.
Limits the search to a folder and its subfolders, such as /policies. A trailing slash names the same folder, and / alone is the whole drive.
Narrows the search. A document must match every filter you set.
Show Fields of filters
Tags a document must have, such as ["legal", "2026"]. With more than one, a document must have every one.
One or more of pdf, docx, txt, md, html, pptx, xlsx, eml, code.
An ISO 8601 date or time, inclusive. A date starts at 00:00 UTC.
An ISO 8601 date or time, inclusive. A date covers the whole day in UTC. Can't be earlier than updated_after.
Returns at most one passage per document. Defaults to true.
Response
Identifies this search. Errors raised by the search itself carry one too.
Up to 10 passages, best first. May be empty.
Show Fields of a result
The passage ID.
The drive containing the document.
The document containing the passage.
The document revision that the byte positions refer to.
The passage text.
The value results are ranked by. Only compare scores within a single search.
high only. Marks a passage chosen as direct support for the question; picked passages come first.
Where the passage starts in the document text, as a UTF-8 byte position.
Where the passage ends, exclusive.
page (PDF and other files with pages), slide (PowerPoint), sheet (Excel), heading_path (the headings above the passage, outermost first), and before and after (up to 300 characters of text on each side).
Each result's file, once, in the order the results first name it. Join a result to its file by document_id. A file renamed or moved after it was indexed shows its current name, path and folder. A file deleted after it was indexed is left out, and its results still come back. Empty when there are no results.
Show Fields of a document
The document, as the results name it.
The drive the document is in.
The file name: the last part of path, such as customer-refund-policy.pdf.
The file's path in its drive, as it is now.
The file's folder, as it is now.
The document's current revision. A result's own revision is the one its byte positions refer to; this one is newer when the file changed after it was indexed.
The effort the search used.
How long the search took, in milliseconds.
Errors
| Status | Code |
|---|---|
| 400 | INVALID_REQUEST |
| 402 | BALANCE_EXHAUSTED |
| 403 | FORBIDDEN |
| 500 | INTERNAL_ERROR |
| 503 | SEARCH_UNAVAILABLE, DRIVE_UNAVAILABLE |
| 504 | TIMEOUT |
See Errors and retries.
Example
curl https://byterover.ai/api/v1/search \
-H "Authorization: Bearer $BYTEROVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Which policy section covers EU refunds?",
"drive_ids": ["drv_4h7k2m9q8r1t5v6w3x0y"],
"effort": "medium"
}'{
"search_id": "srch_8f2k1m0q7r3t",
"results": [
{
"passage_id": "psg_2c9d",
"drive_id": "drv_4h7k2m9q8r1t5v6w3x0y",
"document_id": "doc_7n4p1s8v2x5z9b3d6f0h",
"revision": 3,
"text": "Customers in the European Union may cancel an order within 14 days of delivery and receive a full refund.",
"score": 0.94,
"start_byte": 18244,
"end_byte": 18349,
"location": {
"page": 6,
"heading_path": ["Refunds", "European Union"],
"before": "",
"after": ""
}
}
],
"documents": [
{
"document_id": "doc_7n4p1s8v2x5z9b3d6f0h",
"drive_id": "drv_4h7k2m9q8r1t5v6w3x0y",
"name": "customer-refund-policy.pdf",
"path": "/policies/customer-refund-policy.pdf",
"folder": "/policies",
"revision": 3
}
],
"effort": "medium",
"search_ms": 812
}