REST & webhook API — Parelion Docs

/ 01Overview

Three logical APIs are mounted on the engine: the analysis engine (/api/v1/*), Sentinel (/api/sentinel/v1/*), and Ledger (/api/ledger/v1/*). They share authentication, rate limiting, and audit middleware.

All routes return JSON. All errors follow RFC 9457 (Problem Details). All timestamps are RFC 3339 UTC.

/ 02Authentication

Three modes, configured per tenant:

Mode	Header	Use case
Anonymous	—	Beta, evaluation, demo
API Key	`X-Redline-Key: ...`	Server-to-server
SSO (Clerk)	`Authorization: Bearer ...`	Browser / Word add-in

RBAC scopes

API keys and JWTs carry product:role tuples. E.g. sentinel:admin, lens:editor, ledger:viewer. See Getting started for the role grid.

/ 03Analyse routes

POST/api/v1/analyseAnalyse a plain-text document. Blocks for up to 60s.

POST/api/v1/analyse-docxMulti-part upload of a DOCX file. Returns the same shape as /analyse.

POST/api/v1/upload-and-analyseAuto-detects the upload format (DOCX, PDF, plain text).

POST/api/v1/analyse/streamServer-Sent Events stream of per-pass progress.

GET/api/v1/analyse/{id}Retrieve a stored analysis by ID.

/ 04Export routes

POST/redline-docxDOCX with tracked changes.

POST/report/pdfBranded PDF report.

POST/export/combined-docxCombined report + annotated document + appendix.

POST/export/fieldbookPortable .fieldbook ZIP.

POST/export/fieldbook-htmlSelf-contained HTML viewer.

See Export formats & their guarantees for the per-format contract.

/ 05Sentinel routes

GET/api/sentinel/v1/impactsList impact assessments.

GET/api/sentinel/v1/feedPaginated change feed.

POST/api/sentinel/v1/bills/pollForce a poll against a source.

GET/api/sentinel/v1/dashboard/overviewPortfolio health summary.

PUT/api/sentinel/v1/alerts/preferencesUpdate alert preferences.

Full Sentinel surface: see Sentinel feeds & webhook payloads.

/ 06Ledger routes

GET/api/ledger/v1/obligationsList obligations.

GET/api/ledger/v1/obligations/overduePast deadline, unsatisfied.

PUT/api/ledger/v1/obligations/{id}/statusUpdate lifecycle state with audit trail.

GET/api/ledger/v1/calendar.icsVCALENDAR feed.

POST/api/ledger/v1/escalationsScan for escalation triggers.

/ 07Webhooks

Configure webhook destinations under Settings → Webhooks. Each destination has a secret used to sign outgoing payloads.

Event	Trigger
`analysis.completed`	An `/analyse` call finishes
`sentinel.impact.detected`	Impact assessment with severity ≥ minor
`ledger.obligation.overdue`	Obligation crosses its deadline
`ledger.escalation.triggered`	Escalation tier advances

Signing: X-Parelion-Signature: sha256=<hex> over the raw body with the destination secret. Replay protection via X-Parelion-Timestamp (±5 minutes).

/ 08Rate limits

Tier	Per minute	Per day
A · Free	10	200
B · Paid	60	5,000
C · Enterprise	240	Unlimited

Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Exceeded → HTTP 429 with Retry-After.

/ 09OpenAPI

The full spec is served from the engine itself:

GET/openapi.jsonOpenAPI 3.1 document for the engine + Sentinel + Ledger. Use this with codegen tools.

GET/docsSwagger UI rendering of the same spec.

REST & webhook API.