HTTP API reference

Integrate DocuLens in your backend

REST endpoints for health checks, quotas, reusable field schemas (fieldsets), document analysis previews, and full structured extraction from PDFs and images. Authenticate every protected call with your API key.

Base URL

Endpoint root

All paths below are appended to your DocuLens API base.

https://api.frism.ai/api/doculens

Authentication

API key

Create a key from the workspace (Account → API Keys). Send it on every request that requires authorization:

X-Api-Key: <YOUR_API_KEY>

Keys are tied to your quota. Store them as secrets — never expose them in browser bundles or public repos. /health does not require a key.

Playground

Try endpoints with your API key

GET /quota

Field schema

Payload shape for extraction & fieldsets

Each field is a JSON object with name, type, description, and required. Nested structures use optional fields arrays (for object and list<object>), where each nested item includes name, type, and description.

Allowed types

stringnumbercurrencypercentagedatebooleanlistobjectlist<object>
[
  {
    "name": "invoice_total",
    "type": "currency",
    "description": "Total amount payable including tax",
    "required": true
  },
  {
    "name": "line_items",
    "type": "list<object>",
    "description": "Each purchased line item",
    "required": false,
    "fields": [
      { "name": "sku", "type": "string", "description": "Product or SKU code" },
      { "name": "amount", "type": "currency", "description": "Line total" }
    ]
  }
]

Document requests

Query parameters

ParameterApplies toDescription
start_page/analyze, /extract-fields1-based start of page range (optional).
end_page/analyze, /extract-fields1-based end of page range (optional).
speed/analyze, /extract-fieldsOCR / model speed tradeoff: Auto, Fast, Thinking, or Extreme.

Analyze returns a dry-run style preview (pages, routing, credit estimates) without full field extraction. Extract runs OCR and LLM extraction and returns structured fields with confidence and optional page provenance.

Endpoints

Reference

GET/health

Service health

No auth required. Returns JSON such as { "status": "healthy" } when the service is up.

curl -sS "https://api.frism.ai/api/doculens/health"
GET/quota

Quota & identity

Returns auth mode, user summary, and credit balance for the API key holder.

curl -sS "https://api.frism.ai/api/doculens/quota" \
  -H "X-Api-Key: <YOUR_API_KEY>"
GET/fieldsets

List fieldsets

Returns saved schema templates (metadata and field counts). Requires API key.

curl -sS "https://api.frism.ai/api/doculens/fieldsets" \
  -H "X-Api-Key: <YOUR_API_KEY>"
GET/fieldsets/{id}

Get one fieldset

Fetch a single fieldset by ID including full field definitions.

curl -sS "https://api.frism.ai/api/doculens/fieldsets/<FIELDSET_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>"
POST/fieldsets

Create fieldset

JSON body: name, optional description, and fields array.

curl -sS -X POST "https://api.frism.ai/api/doculens/fieldsets" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{"name":"Invoices","description":"Standard invoice schema","fields":[{"name":"invoice_total","type":"currency","description":"Total payable including tax","required":true}]}'
DELETE/fieldsets/{id}

Delete fieldset

Removes a saved fieldset. Success is typically HTTP 204 with an empty body.

curl -sS -X DELETE "https://api.frism.ai/api/doculens/fieldsets/<FIELDSET_ID>" \
  -H "X-Api-Key: <YOUR_API_KEY>"
POST/analyze

Analyze document

multipart/form-data with a single file field file.

curl -sS -X POST "https://api.frism.ai/api/doculens/analyze?start_page=1&end_page=3&speed=Fast" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "file=@./document.pdf"
POST/extract-fields

Extract fields

multipart/form-data: file (PDF or image) and fields (JSON string matching the schema format above).

curl -sS -X POST "https://api.frism.ai/api/doculens/extract-fields?speed=Auto" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -F "file=@./document.pdf" \
  -F 'fields=[{"name":"invoice_total","type":"currency","description":"Total payable including tax","required":true}]'

Errors

Common HTTP statuses

  • 401Unauthorized — invalid or missing API key.
  • 402 / 429Quota or billing constraints — response body usually includes a detail string.
  • 4xxValidation errors may return FastAPI-style detail (string or list of objects with msg).

Get API keys in the workspace

Sign in with Google, open Account → API Keys, and create a key for server-side calls.