Document Management

After upload, document management covers four common tasks: listing encrypted document records, downloading encrypted content, deleting documents, and retrieving encrypted OCR output from enclave processing.

The application server returns encrypted metadata and encrypted content. Clients unwrap the relevant document key and decrypt locally.

For the upload flow itself, see Document Upload.

Endpoint sequence:

• GET /v1/documents
• GET /v1/documents/{id}/content
• DELETE /v1/documents/{id}
• GET /v1/documents/{id}/ocr-result

Use the API Reference for exact parameters, response bodies, and errors.

List Documents

Endpoint: GET /v1/documents

Listing returns paginated encrypted document records. The application server can return document IDs, status, timestamps, size bucket, commitment nonce, wrapped document key material, and encrypted metadata. It does not receive plaintext metadata.

The client unwraps the document key, then decrypts metadata locally.

Download Encrypted Content

Endpoint: GET /v1/documents/{id}/content

Document content is downloaded as encrypted bytes. Owners use the authenticated owner path. Grantees use the grant access path with the active grant and claim token.

If content has not been uploaded yet, download fails because the document is still pending_upload.

Depending on storage behavior and size, Literal may return encrypted bytes directly, stream encrypted bytes, or return a presigned download URL. In all cases, the client decrypts the content locally using the document key available through the owner or grant access path.

Delete A Document

Endpoint: DELETE /v1/documents/{id}

Deleting a document removes active access to the document record and deletes the encrypted object from storage. If storage deletion fails, cleanup is queued for retry.

The endpoint returns 404 whether the document does not exist or the caller is not authorized.

Retrieve Encrypted OCR Output

Endpoint: GET /v1/documents/{id}/ocr-result

After enclave processing, Literal may return encrypted OCR output for supported documents. The response can indicate that processing is still pending, failed, or complete.

When complete, the OCR text is returned encrypted along with wrapped key material needed for local decryption. OCR job records expire 24 hours after completion; later requests return not found.

Troubleshooting

• If download fails, confirm the document is no longer pending_upload.
• If a document is not found, it may not exist or the caller may not be authorized.
• If OCR output is unavailable, processing may still be pending, may have failed, or the OCR record may have expired.
• If deletion succeeds but storage cleanup is delayed, Literal queues cleanup for retry.

For exact status codes and response bodies, see Error Handling and the API Reference.

Related Resources

• Document Upload — the upload flow that creates document records.
• Document Lifecycle — processing states from upload to deletion.
• Grants & Sharing — understand grant-based access to shared documents.
• Creating And Claiming Grants — implement the grant workflow, including the grantee download path.
• Job Polling — tracking background operations by job ID.

Last updated on