Files: types, status and revisions
Which files ByteRover reads, when a file becomes searchable, and what happens when a file changes.
A file is one document in a drive, with a path, a status, one or more revisions, and optional tags.
File types
ByteRover tells a file's type from the ending of its name. Files can be up to 1 GB, with a lower practical limit for Word, PowerPoint and Excel files (see Size limits).
| Type | File names that end in |
|---|---|
.pdf | |
| Word | .docx |
| PowerPoint | .pptx |
| Excel | .xlsx |
| HTML | .html, .htm |
| Markdown | .md, .markdown, .mdx |
| Text | .txt, .text, .csv |
.eml | |
| Code | See the list below |
Files with any other ending are refused.
Size limits
- Every file can be up to 1 GB.
- Word, PowerPoint and Excel files are read whole, with a memory limit and a time limit of 2 minutes plus 1 minute for each 50 MB. A file that passes either limit is Not searchable, and the reason names the limit. A very large or complex file of these types can hit a limit below 1 GB.
- A team's first 1 GB of storage is free. Past it, an upload is refused with
BALANCE_EXHAUSTED(status 402) when the team's balance is empty. An owner or admin can add to the balance on the Billing page. Files already uploaded stay readable.
What ByteRover reads in each type
| Type | What is read | Where the heading path comes from |
|---|---|---|
| The text of each page | The PDF's outline (bookmarks). A PDF without bookmarks has no heading path. | |
| Word | The text | Word's heading styles |
| PowerPoint | Each slide's text and its speaker notes | The slide's title |
| Excel | Each sheet's rows. The first row of a sheet is searched with every passage from that sheet. | None. Each passage names its sheet. |
| HTML, Markdown | The text | The document's headings |
| The message text. From, to and date are kept with the file. Attachments are skipped. | The subject | |
| Text, code | The text | None |
ByteRover doesn't read words inside pictures, in any file type.
A passage from a PDF carries its page, a passage from a presentation its slide, and a passage from a spreadsheet its sheet.
PDF pages
A PDF is read one page at a time.
- A page that can't be read, takes more than 30 seconds, or has more than 16 MB of text is skipped. The rest of the file stays searchable.
- The whole file also has a time limit of 2 minutes plus 1 minute for each 50 MB. When it runs out, the pages not yet read are skipped, and the pages already read stay searchable.
- The app and the API don't list skipped pages yet. If a search can't find text you can see on a page, that page may have been skipped.
Scanned PDFs
ByteRover can't read a PDF that's only images yet. A scan or photo of a page has no text, so there's nothing to search. Support for these files is on the way.
Such a PDF still uploads, but its status is Not searchable, and the reason is "This PDF contains only images. Image-only PDF text extraction is not supported yet." A PDF with no text at all, such as one with only drawings, gets the same status and reason. In the API, the document's error_code and its operation's error code are both IMAGE_ONLY_PDF_UNSUPPORTED.
Until then, upload PDFs that have text. To check, open the PDF and try to select a word; if you can, it has text.
In a PDF with both text and pictures, ByteRover reads the text but not any words inside the pictures.
Status
After an upload, ByteRover reads the file and prepares it for search. The status shows how far along it is.
| In the app | In the API | Meaning |
|---|---|---|
| Queued | queued | The file is waiting its turn. |
| Extracting | extracting | ByteRover is reading the file's text and structure. |
| Indexing | indexing | ByteRover is preparing the text for search. |
| Saving | persisting | The result is being saved. |
| Searchable | searchable | Searches can find the file. This status is final. |
| Not searchable | failed | ByteRover couldn't read the file. The reason is shown next to the file. This status is final. |
Not every file shows every step. When a step fails for a reason that may pass, such as the drive's index being briefly unavailable, ByteRover tries again and the status goes back to Queued. If the uploaded file doesn't match the checksum it was sent with, the status is Not searchable.
Reading a file is limited to 2 minutes plus 1 minute for each 50 MB, so most files are searchable well within that. A file waiting behind others in the queue takes longer.
A new file is searchable once its status is Searchable, so wait for that status before asking about it.
Revisions
To replace a file, upload the new version with the same name to the same folder. When you upload to a path that already has a file, ByteRover adds a revision to that file instead of making a second one.
- While the new revision is being read, searches keep finding the previous revision. The new one replaces it in a single step once it's ready, so a search never sees half of each.
- If the new revision is Not searchable, searches can still return passages from the previous revision. Delete the file or upload a version that reads, and those passages go away.
- Earlier revisions are kept until you delete the file, and you can open and download each of them.
- Each passage in a result names the revision it came from.
Tags
A tag is a label you put on a file, such as legal or 2026 budget. You can limit a search to files that have the tags you list. With more than one tag, a file must have every one.
- A file can have up to 32 tags, and the same tag can't be listed twice.
- A tag is 1 to 64 characters long. It can't contain
=or control characters.
What a delete removes
Deleting a file makes it unsearchable and deletes the original file along with all its revisions. You can't undo this.
Where you use it
- In the app: Upload files.
- With an agent: the
uploadtool, or thewritetool for a text file. - With the API: Upload files and Limits.