System overview

A complete picture of how ExDocApi works — from API call to extracted JSON.

Architecture

YOUR APPLICATION
  |
  | POST /api/v1/extract (file + fields)
  v
API LAYER
  |- Auth: validates API key (SHA-256 hash)
  |- Credit Check: returns 402 if insufficient
  |- Job Manager: stores file, creates job
  |
  v
DATABASE
  |- jobs, profiles, api_keys
  |- usage_ledger, schemas
  |
  v
PROCESSING WORKERS
  |
  | Worker 1: Document Parser
  |   Input:  PDF or image
  |   Output: structured text
  |
  v
  | Worker 2: Extraction Engine
  |   Input:  text + your field definitions
  |   Output: JSON { field: value }
  |
  v
Result saved to database
Credits debited from account
  |
  v
YOUR APPLICATION
  | GET /api/v1/jobs/:id  (poll)
  | GET /api/v1/jobs/:id/result

Request flow — step by step

Step 1 — Submit Your app sends POST /api/v1/extract. The API validates your key, checks credits, estimates page count, uploads the file to secure storage, and creates a job record.

Step 2 — Parse The job is dispatched to Worker 1. It receives the file, converts PDF/image to structured text, and calls back to the webhook with the result.

Step 3 — Extract The webhook receives the parsed text and dispatches to Worker 2 along with your field definitions. Worker 2 locates each field using accurate AI filtering algorithms and calls back with the JSON result.

Step 4 — Complete The result JSON is saved to the job, status is set to done, and credits are debited from your account.

Step 5 — Retrieve Your app polls GET /api/v1/jobs/:id until status is done, then fetches the result.

Queue system

Jobs are processed in priority order when multiple are submitted simultaneously.

| Priority | Source | |----------|--------| | 90 | Enterprise plan | | 70 | Paid plan | | 55 | API source | | 40 | Playground / other |

Within the same priority level, jobs are processed FIFO (oldest first).

Data model

profiles — one per user. Stores credit balance, plan, and role.

api_keys — one or more per user. Only the SHA-256 hash is stored, never the plaintext key.

jobs — one per extraction request. Tracks status, file, extraction request, result, and which user/key submitted it.

schemas — reusable field sets. Stored per user, referenced by jobs.

usage_ledger — every credit event (extraction debit, purchase credit) logged here.

Security model

API keys are never stored in plaintext. Only a SHA-256 hash is kept in the database. When you authenticate, the incoming key is hashed and compared — the original is never recoverable.

File storage uses private, access-controlled storage. Files are referenced by a random path and are not publicly guessable.

Row-level security ensures users can only access their own jobs, schemas, and usage data. The API layer uses a service role that bypasses RLS for controlled server-side access.

Webhook secrets protect the internal callback endpoints from unauthorized calls.