Skip to main content

​
Principle

Use a simple split:
  • Public, cacheable reads for explicitly published artifacts
  • Private, authenticated reads for account/document state
  • Private, authenticated writes for all mutations
In short: read public, write private.

​
Route classes

​
Public read surface (/v1/documents/...)

Designed for published/shareable outputs and CDN caching. Examples:
  • GET /v1/documents/{id}
  • GET /v1/documents/{id}/pages/{n}/image
  • GET /v1/documents/{id}/entities/tables/{index}
These endpoints must never allow mutation.

​
Private authenticated surface (/document/...)

Designed for operational state, configuration, and mutations. Examples:
  • GET /document/{id}/config
  • PUT /document/{id}/config
  • POST /document/{id}/reparse
  • POST /document/{id}/extract
All requests require API-key or shared-secret auth.

​
/v1 write routing

For consistency, non-GET requests under /v1/documents/{id}/... are rewritten to /document/{id}/... before handling. This keeps a clean external namespace while preserving private/authenticated mutation handling.

​
Caching rule

  • Public routes: cacheable (public)
  • Private routes: non-public cache headers (private/no-store) for config/state
Do not cache private document configuration in public caches.