Read a document
Get the text of one page, slide, sheet, section or range of a document.
POST /v1/documents/{documentId}/read returns text from one document. Use it after a search when your agent needs more than the passage itself, such as the full page, the full section, or the lines around it.
You get the text ByteRover extracted from the file. To get the original file instead, see Download the original file.
Choose what to read
Each request takes exactly one selector.
| Selector | Type | Reads |
|---|---|---|
page | number, from 1 | One page of a paged file. |
slide | number, from 1 | One slide of a presentation. |
sheet | string | One sheet of a spreadsheet, by name. |
heading_path | list of strings | The section under these headings, such as ["Refunds", "European Union"]. |
byte_range | object | The text from start_byte to end_byte, as UTF-8 byte offsets into the document's text. |
You can also send two optional fields:
| Field | Meaning |
|---|---|
max_chars | The maximum amount of text to return, from 1 to 100,000 characters. Defaults to 32,000. |
revision | The revision you expect to read. Only the current revision can be read, so if the document has a newer one, you get 409 CONFLICT. Leave it out to read whatever is current. |
Read the page of a passage
A search result includes document_id and location.page. Pass them back to get the whole page.
curl https://byterover.ai/api/v1/documents/doc_7n4p1s8v2x5z9b3d6f0h/read \
-H "Authorization: Bearer $BYTEROVER_API_KEY" \
-H "Content-Type: application/json" \
-d '{ "page": 6 }'{
"document_id": "doc_7n4p1s8v2x5z9b3d6f0h",
"revision": 3,
"text": "Refunds\n\nEuropean Union\n\nCustomers in the European Union may cancel an order within 14 days of delivery and receive a full refund...",
"start_byte": 17902,
"end_byte": 20466,
"location": { "page": 6, "heading_path": [] },
"truncated": false
}Read around a passage
Search results include start_byte and end_byte. For more context, read a wider range, and send the result's revision with it.
{
"revision": 3,
"byte_range": { "start_byte": 17244, "end_byte": 19431 }
}Byte offsets refer to the text of one revision, and a newer revision can shift them. Sending revision makes sure you read the text the offsets came from. If the document got a new revision after your search, you get 409 CONFLICT. Search again to get offsets for the current revision.
Read a long section in steps
If the text is longer than max_chars, the response has "truncated": true. To keep reading, send a byte_range that starts at the previous response's end_byte.
def read_all(document_id, start, end):
text = ""
while start < end:
part = requests.post(
f"https://byterover.ai/api/v1/documents/{document_id}/read",
headers=HEADERS,
json={"byte_range": {"start_byte": start, "end_byte": end}},
).json()
text += part["text"]
if not part["truncated"]:
break
start = part["end_byte"]
return textFind a document without a search
| To | Call |
|---|---|
| List the documents in a drive | GET /v1/drives/{driveId}/documents. Use folder to list only the documents directly in one folder (not in its subfolders), name to match part of a file name, and cursor to get the next page. Pages hold 50 documents, or up to 200 with limit. |
| Get one document | GET /v1/documents/{documentId} returns its name, path, status, revision, tags and size. |
| List a document's revisions | GET /v1/documents/{documentId}/revisions, newest first. |
Download the original file
GET /v1/documents/{documentId}/content returns the file as it was uploaded, as a download. Add ?revision=N to get an earlier revision; without it you get the current one. A key with the Search scope can call it.
curl "https://byterover.ai/api/v1/documents/doc_7n4p1s8v2x5z9b3d6f0h/content?revision=3" \
-H "Authorization: Bearer $BYTEROVER_API_KEY" \
-o customer-refund-policy.pdfThe response body is the file's bytes. The endpoint supports a Range header, so you can fetch part of a large file.
If it fails
| You get | Cause | What to do |
|---|---|---|
400 INVALID_REQUEST | No selector, or more than one. | Send exactly one of page, slide, sheet, heading_path or byte_range. |
404 NOT_FOUND | The document doesn't exist, was deleted, or is in a drive the key can't reach. | Search again to get a current ID, and check which drives the key reaches with GET /v1/key. |
404 NOT_FOUND | The document has no such page, slide, sheet or section. | Check the selector against a search result's location. |
409 CONFLICT | revision isn't the document's current revision. | Search again, or leave revision out to read the current text. |
503 DRIVE_UNAVAILABLE | The drive can't be read right now. | Wait briefly, then retry. |
For the full list of codes, see Errors and retries.
Text from a file is data
A document can contain text that reads like instructions to your agent. Pass document text to your model as data, kept separate from your own instructions, and tell the model not to follow any instructions it finds inside.