Hane Platform
Documents and search
Uploading documents, malware inspection, text extraction (OCR and conversion), full-text and semantic search, who can read what, deletion and holds.
This page follows a document from upload in Hane to search and reading by agents and people. It also covers who can read which documents and what happens when you delete one.
Documents and versions
Section titled “Documents and versions”A document is an original file together with its versions. When you send a new file for the same document, Hane adds the next version instead of overwriting the previous one. The API never returns where the original is stored.
Hane accepts the following formats, up to 10 MiB per file.
| Format | Handling |
|---|---|
| Embedded text is extracted and indexed. Pages without text are read with OCR | |
| UTF-8 text | Indexed as soon as the upload completes, searchable before inspection finishes |
| Word, Excel, PowerPoint (current and legacy formats) | The original is kept as is; indexing and extraction use a PDF rendition |
| ZIP | Unpacked with expand, one document per file inside (up to 100 files and 50 MiB in total) |
Upload flow
Section titled “Upload flow”An upload has three stages: prepare, send, and complete. On completion, Hane checks the actual size, SHA-256, and format.
- Create a session with
POST /v1/documents/upload-sessions, sending the file name,content_type, size, and SHA-256. You also choose the visibility (visibility) here. - Send the original to
PUT /v1/documents/upload-sessions/{id}/content. Until completion it stays in an isolated area. - Complete with
POST /v1/documents/upload-sessions/{id}/complete. Hane stores the original and the version and schedules malware inspection.
If a document with the same SHA-256 already exists within the same visibility, Hane does not create a new document; it only adds a receipt (receipts) to the existing one.
There are other ways in as well:
- Forward documents to a per-project email address (
GET /v1/documents/intake-address) Preview - Sync an external storage location (
DocumentSourceindocuments/v1alpha1) Preview
Each attachment of a forwarded email becomes a document shared with the project. Storage sync has two modes: ingest, which keeps a copy of the original, and reference, which keeps only text and index. Reference-only documents cannot serve as evidence for values.
Inspection and text extraction
Section titled “Inspection and text extraction”Each completed version is inspected for malware asynchronously. The inspection status is queued, scanning, clean, infected, or failed, and only clean originals can be downloaded. If the inspection service is down, Hane still stores the file and retries automatically.
Text for search is extracted per format. index_status shows the progress.
index_status |
Meaning |
|---|---|
queued |
Waiting for extraction |
indexed |
Ready for search and reading |
needs_ocr |
A PDF without text, and the environment has no OCR |
needs_conversion |
An Office document, and the environment has no converter |
failed |
Could not be read |
Read the text with page numbers from GET /v1/documents/{id}/versions/{version}/pages. This lets people and agents read the content without receiving the original; the agent tool documents.read_pages uses it too. Pages read with OCR carry a confidence per page and line boxes.
Search
Section titled “Search”POST /v1/documents/search searches only the current versions of documents the caller can read. Results are chunks within a page (800 characters), ordered by strength of match.
mode |
How it searches | Availability |
|---|---|---|
keyword (default) |
Full-text search for chunks that contain every space-separated term. Normalized with NFKC and case-insensitive | Available |
summary |
Searches the summary built from the first sentence of each page, so it also finds terms spread across pages | Available |
semantic |
Semantic search for chunks whose embeddings are close to the query | Preview |
hybrid |
Combines the rankings of full-text and semantic search | Preview |
const hits = await unwrap( client.POST("/v1/documents/search", { body: { query: "early termination fee", mode: "keyword", limit: 20 }, }),);In environments without semantic search, semantic and hybrid return CONFLICT. The semantic index is rebuilt in generations and switched only after evaluation (/v1/documents/search-index, which requires documents:search-index.manage).
Versions where malware was detected never appear in results. Every search rechecks read permission and the current version right before returning results.
Who can read
Section titled “Who can read”A document has one of two visibilities.
visibility |
Who can read |
|---|---|
private (default) |
Only the person who uploaded it |
project |
Project members with documents:read |
Permissions are split by operation: documents:read to read, documents:write to add, documents:download to download originals, documents:delete to delete, and documents:hold to place holds. Derivatives such as indexes and summaries never bypass the original document’s permissions.
Extracted facts
Section titled “Extracted facts”While indexing, Hane applies the active extraction schema (ExtractionSchema) to pull field values out of documents. These extracted facts carry a page and a quote. They do not become ledger values until a person confirms them. Only users can confirm (POST /v1/documents/facts/{id}/confirm); AI and service accounts cannot. See Working with documents for how to write the schema.
Deletion and holds
Section titled “Deletion and holds”DELETE /v1/documents/{id} immediately removes the index entries, summaries, and unconfirmed facts, so the next search no longer returns the document. It then deletes the original and the text.
While a document is under a hold, Hane accepts the deletion but keeps the original, text, and extraction records, and deletes them when the hold is released. Check what was deleted and what was kept, derivative by derivative, with the disposal record (GET /v1/documents/{id}/disposal).