API Reference
Workflow API
All endpoints require a signed-in session (cookie) unless noted. Responses are JSON: { ok: true, data } or { ok: false, error }. Common errors: 400 validation, 401 unauthenticated, 403 forbidden, 404 not found, 429 rate-limited, 502/503 upstream. Public /api/v1 endpoints authenticate with Authorization: Bearer pdflean_… and must send a JSON content type.
Workflows
| Method | Path | Description |
|---|---|---|
| GET | /api/workflows | List your workflows |
| POST | /api/workflows | Create a workflow (draft) |
| GET | /api/workflows/:id | Get a workflow |
| PUT | /api/workflows/:id | Update a workflow (draft, version+1) |
| DELETE | /api/workflows/:id | Delete a workflow |
| POST | /api/workflows/:id/publish | Publish a version |
| GET | /api/workflows/:id/versions | List versions |
| POST | /api/workflows/:id/versions/:version/restore | Restore a version |
Triggers & Hooks
| Method | Path | Description |
|---|---|---|
| GET | /api/workflows/triggers | List triggers |
| POST | /api/workflows/triggers | Create a trigger (webhook/schedule/email/drive) |
| POST | /api/workflows/triggers/:id/run | Run a trigger now |
| DELETE | /api/workflows/triggers/:id | Delete a trigger |
| POST | /api/workflows/hook/:token | Inbound webhook (token auth, no session; JSON body) |
Runs & Reviews
| Method | Path | Description |
|---|---|---|
| POST | /api/workflows/runs | Create a run (queued) |
| GET | /api/workflows/runs | List runs |
| GET | /api/workflows/runs/:id | Run details and steps |
| POST | /api/workflows/runs/:id/retry | Retry a failed/queued run |
| GET | /api/workflows/reviews | Pending human reviews |
| POST | /api/workflows/reviews/:id | Approve/reject a review |
Cloud Bridge
| Method | Path | Description |
|---|---|---|
| GET | /api/workflows/cloud/status | Standalone VPS bridge status |
| POST | /api/workflows/cloud/convert | Office → PDF via standalone VPS (LibreOffice) |
| POST | /api/workflows/cloud/ocr | OCR via standalone VPS (Tesseract) |
| POST | /api/workflows/cloud/extract | Extract invoice/generic fields from PDF (pdfjs + rules) |
Archive & Retention
| Method | Path | Description |
|---|---|---|
| GET | /api/workflows/archive | List archived documents and chain integrity |
| POST | /api/workflows/archive | Archive a document (base64, SHA-256 hash chain) |
| GET | /api/workflows/archive/:id/verify | Verify the archive hash chain |
| GET | /api/workflows/archive/export | Export archive audit CSV (includes tombstones) |
| POST | /api/workflows/archive/:id/hold | Set/clear legal hold |
| POST | /api/workflows/archive/:id/compliance | Enable irreversible WORM compliance lock |
| DELETE | /api/workflows/archive/:id | Delete an archive (blocked under legal hold) |
Public API v1
| Method | Path | Description |
|---|---|---|
| GET | /api/v1/openapi.json | OpenAPI 3.1 spec (public, no auth) |
| GET | /api/v1/me | Current API key owner (Bearer key) |
| GET | /api/v1/usage | Usage dashboard: balance, 30-day history, recent calls |
| GET | /api/v1/workflows | List workflows (scope workflow.read) |
| GET | /api/v1/workflows/:id | Get a workflow (scope workflow.read) |
| POST | /api/v1/workflows/:id/run | Queue a run (scope workflow.run) |
| GET | /api/v1/runs | List runs (scope workflow.read) |
| POST | /api/v1/pdf/merge | Merge PDFs (scope pdf.merge; 2–10 base64 files) |
| POST | /api/v1/pdf/split | Keep selected pages (scope pdf.split; ranges like "1-3,5") |
| POST | /api/v1/pdf/compress | Structurally compress a PDF (scope pdf.compress) |
| GET | /api/v1/jobs/:id | Job status (free) |
| GET | /api/v1/jobs/:id/download | Download a job result (free) |
| POST | /api/v1/convert/office | Convert Office/ODF documents (scope pdf.convert) |
| POST | /api/v1/convert/linearize | Linearize a PDF for fast web view (scope pdf.convert) |
| POST | /api/v1/convert/typst | Compile Typst/Markdown source to PDF (scope pdf.convert) |
| POST | /api/v1/ocr | OCR a scanned PDF into a searchable PDF (scope pdf.ocr) |
| POST | /api/v1/ocr/text | OCR a single image to text (scope pdf.ocr) |
| POST | /api/v1/validate/pdfa | PDF/A compliance check (scope pdf.validate) |
| POST | /api/v1/validate/pdfua | PDF/UA accessibility check (scope pdf.validate) |
| POST | /api/v1/validate/signature | Digital signature verification report (scope pdf.validate) |
| POST | /api/v1/sign | PAdES digital signature (scope pdf.sign; optional PEM key pair) |
| POST | /api/v1/redact | True redaction of text matches or areas (scope pdf.redact) |
| POST | /api/v1/extract | Text and rule-based field extraction (scope pdf.extract) |
| POST | /api/v1/docling | Structured layout parsing via Docling (scope pdf.extract) |
| POST | /api/v1/scan/pii | Scan text for personal information (scope pii.detect) |
额度消耗
每月获赠额度随订阅计费周期刷新（不结转），先用赠送后扣充值，额度单价 $0.001（后台可配）。
| Method | Endpoint | 额度 |
|---|---|---|
| GET | /jobs/:id | 0 /次 |
| GET | /jobs/:id/download | 0 /次 |
| GET | /me | 0 /次 |
| GET | /runs | 0 /次 |
| GET | /usage | 0 /次 |
| GET | /workflows | 0 /次 |
| GET | /workflows/:id | 0 /次 |
| POST | /ai/chat | 3 /次 |
| POST | /ai/extract | 5 /次 |
| POST | /ai/pii-detect | 4 /次 |
| POST | /ai/summarize | 3 /次 |
| POST | /ai/translate | 3 /次 |
| POST | /convert/linearize | 1 /次 |
| POST | /convert/office | 2 /次 |
| POST | /convert/typst | 1 /次 |
| POST | /docling | 3 /次 |
| POST | /extract | 2 /次 |
| POST | /ocr | 3 /页 |
| POST | /ocr/text | 1 /次 |
| POST | /pdf/compress | 1 /次 |
| POST | /pdf/merge | 1 /次 |
| POST | /pdf/split | 1 /次 |
| POST | /redact | 3 /次 |
| POST | /scan/pii | 2 /次 |
| POST | /sign | 5 /信封 |
| POST | /validate/pdfa | 2 /次 |
| POST | /validate/pdfua | 2 /次 |
| POST | /validate/signature | 2 /次 |
| POST | /workflows/:id/run | 1 /次 |
| ai.chat | 2 /次 | |
| convert.html_to_pdf | 4 /页 | |
| convert.office_to_pdf | 10 /页 | |
| convert.pdf_to_office | 12 /页 | |
| convert.pdfa | 8 /页 | |
| esign.envelope | 750 /信封 | |
| pdf.ocr | 3 /页 | |
| pdf.ocr.high | 8 /页 |