Documentation/Service API
Checking service
DOCUMENT INTELLIGENCE API

Turn any document into
structured intelligence.

One private, GPU-powered endpoint for PDFs and images. Supply the document path, extraction instructions, document type, and output format—receive production-ready JSON, text, or HTML.

Try the API →Read quick start
✓Local processing✓Bearer protected✓Schema driven
request.json
{
  "source_document_path": "inputs/invoice.pdf",
  "document_type": "invoice",
  "response_type": "json",
  "instructions": "Extract invoice_number,
    supplier_name and grand_total."
}
200 OKGPU extraction completeStructured response
⌘

One extraction contract

Natural language or descriptor schemas with exact keys, types, and field-specific rules.

◫

Any supported document

Invoices, IDs, policies, certificates, contracts, receipts, forms, tables, and more.

◆

Private by design

Files and model inference remain on your GPU server. No third-party OCR service.

01

QUICK START

Your first extraction in three steps

Set up a protected call in under two minutes.
1

Place the document on the server

The path API reads from approved server directories, configured through OCR_API_SOURCE_ROOTS.

mkdir -p inputs
cp invoice.pdf inputs/
2

Load a bearer token

Use a user token from the admin panel. The master token also works for administrative testing.

SERVICE_TOKEN="your-user-token"
3

Send the request

The call remains open while OCR runs. Use a client timeout suitable for multi-page documents.

curl -X POST http://127.0.0.1:7860/api/v1/extract-path \
  -H "Authorization: Bearer $SERVICE_TOKEN" \
  -H "Content-Type: application/json" \
  -d @request.json
02

AUTHENTICATION

Bearer tokens

Every service request must carry a valid active credential.

Authorization header

Create users and tokens at the admin panel. Generated user credentials are shown once, stored only as hashes, and can be expired or revoked immediately.

iUser tokens can call the extraction service but cannot access administrative APIs. Job files are isolated by calling user.
HTTP
Authorization: Bearer uocr_your_token
Content-Type: application/json
03

API REFERENCE

Extract a server-side document

Runs the same OCR and structured-review pipeline as the browser workspace.
POST/api/v1/extract-path

Submit a document already available to the OCR server. The response is synchronous and contains the extracted content plus job metadata and protected artifact URLs.

Request bodyapplication/json
source_document_pathrequiredstring

Absolute path under an approved root, or a path relative to the project directory.

instructionsoptionalstring

Natural-language requirements or a JSON/JavaScript-like descriptor schema. No application character limit.

document_typedefault: autostring

Authoritative context such as invoice, insurance_policy, aadhaar, certificate, or a custom value.

response_typedefault: jsonenum

One of json, text, or html.

modedefault: gundamenum

gundam uses detailed crops; base reduces memory usage.

max_output_tokensdefault: 4096integer

Output budget from 1,024 to 32,768 tokens.

expected_valuesoptionalobject

Your own key-value JSON for this document. Supplying it returns a field-by-field comparison against our model output and stores the pair for supervised review. Requires response_type: json.

reference_idoptionalstring

Your record identifier, stored with the comparison so you can correlate it later.

04

LIVE PLAYGROUND

Build and run a request

Your token stays in this tab and is sent only to this server.
POST/api/v1/extract-path
Local server
ResponseNot sent
Run the request to inspect the live response.

The extraction may take several seconds or minutes depending on document size and GPU state.

          

        


        

          
05
RESPONSE OBJECT
Everything needed to consume the job
Parsed content, serialized content, provenance, timing, and protected artifacts.

          

            
model_outputobject · string
The AI OCR result as key-value JSON. Same value as content.

            
comparisonobject · null
Field-by-field result against expected_values: match_rate, per-field status, and a suggested_verdict. Null when you send no expected values.

            
review_idnumber · null
Identifier of the stored review record awaiting accept or reject in the admin panel.

            
contentobject · string
Parsed JSON output, or extracted text/HTML for other response types.

            
content_textstring
Serialized output ready to store, display, or forward.

            
job_idstring
Unique identifier for this extraction job.

            
duration_secondsnumber
Total OCR and post-processing duration.

            
preview_urlstring
Bearer-protected snapshot of the source document.

            
raw_urlstring
Bearer-protected raw OCR output for diagnostics.

            
download_urlstring
Bearer-protected final result download.

            
page_countinteger
Number of pages processed from the document.

          

        


        

          
06
ERRORS
Predictable HTTP status codes
All failures return JSON with a human-readable detail.

          
400Invalid parameter or request combination
401Missing, invalid, expired, or revoked token
403Path outside allowed roots or another user’s job
404Source document or job not found
413Document exceeds 100 MB
415Unsupported file type
422Validation, page-limit, or extraction error
507Insufficient GPU memory

        


        

          
07
ADMIN API
Users and credentials
These endpoints accept only the master token.

          

            

              ⌘
              
CONTROL PLANE
Manage access without touching the database
Create a user, issue their scoped bearer credential, and revoke access from one protected workflow.

            

            Open admin console →
          

          

            
01Create userIdentity and access status

            →
            
02Issue tokenCredential shown once

            →
            
03Call OCRJobs remain user-scoped

            →
            
04RevokeAccess stops immediately

          

          

            

              GET/api/admin/summaryInspect users, active credentials, and service activity.+
              
AUTHMaster token
RETURNSAccess metrics

            

            

              GET/api/admin/usersBrowse every user with token and activity metadata.+
              
AUTHMaster token
RETURNSUser collection

            

            

              POST/api/admin/usersCreate a service user with basic identity details.+
              
BODYName, email, company
RETURNSNew user record

            

            

              PATCH/api/admin/users/{user_id}Update profile details or suspend service access.+
              
BODYEditable user fields
EFFECTImmediate update

            

            

              POST/api/admin/users/{user_id}/tokensGenerate a new bearer token, optionally with expiry.+
              
SECRETDisplayed only once
STORAGEHashed at rest

            

            

              DELETE/api/admin/tokens/{token_id}Revoke a credential without deleting its owner.+
              
EFFECTImmediate revocation
RECOVERYIssue a new token

            

          

        


        

          
08
PRODUCTION SECURITY
Deploy with clear boundaries
The API supplies authentication; your edge should supply internet-facing controls.

          
01
Terminate HTTPS
Place the service behind Nginx, Caddy, Cloudflare Tunnel, or another trusted TLS reverse proxy.
02
Restrict source roots
Set OCR_API_SOURCE_ROOTS to dedicated document directories and avoid broad filesystem access.
03
Protect secrets
Keep the master token and SQLite database out of source control. Rotate credentials when access changes.
04
Operate intentionally
Add rate limiting, monitoring, backups, job retention, quotas, and audit logs appropriate to your service.