PhantomDocs API Reference
Programmatic access to document upload, token management, webhooks, and the embeddable viewer. Base URL: http://localhost:5001
Add Authorization: Bearer <token> (session token from /v1/auth/login) or X-API-Key: pk_live_... (API key from /v1/api-keys) to authenticated endpoints.
Authentication
PhantomDocs supports two authentication methods: user session tokens (PASETO Bearer tokens) obtained via login, and API keys (pk_live_...) for programmatic access.
/v1/auth/registerRegister a new user account/v1/auth/loginLog in and receive a session token/v1/auth/meGet the authenticated user profileAPI Keys
API keys (pk_live_...) let you authenticate machine-to-machine requests without a user session. Pass the key in the X-API-Key header.
/v1/api-keysCreate a new API key/v1/api-keysList API keys (keys are masked)/v1/api-keys/:idRevoke an API keyDocuments
Upload, list, view, download, and delete documents. All document payloads must be base64-encoded. The server encrypts the content with AES-256-GCM.
/v1/documentsUpload a new document/v1/documentsList all documents owned by the authenticated user/v1/documents/:id/viewRender the document as an inline HTML viewer/v1/documents/:id/downloadDownload a self-contained HTML file/v1/documents/:idDelete a document and revoke all its tokens/v1/documents/:id/revokeRevoke all tokens for a document (kill switch)/v1/documents/:id/qrGet a QR code PNG for the document download URL/v1/documents/:id/viewersGet the current active viewer count/v1/documents/bulk-revokeRevoke all tokens for multiple documents/v1/documents/bulk-deleteDelete multiple documentsAccess Tokens
Access tokens control who can view a document and for how long. Each token has an expiry, optional view limit, and can be revoked instantly.
/v1/tokensList all access tokens/v1/documents/:id/tokensCreate a new token for a document/v1/documents/:id/tokensList all tokens for a document/v1/tokens/:tokenUpdate a token's view limit and/or expiry/v1/tokens/:token/revokeRevoke a single access tokenWebhooks
Register endpoints to receive HTTP POST callbacks when events occur. Payloads are signed with HMAC-SHA256; verify the X-PhantomDocs-Signature header.
/v1/webhooksRegister a new webhook endpoint/v1/webhooksList registered webhooks/v1/webhooks/:idUpdate a webhook (name, url, events, active)/v1/webhooks/:idDelete a webhook registration/v1/webhooks/:id/testSend a test delivery to verify connectivityAudit & Analytics
All document access events are logged. Query audit logs for forensics and analytics data for dashboards.
/v1/auditList all audit events (paginated)/v1/documents/:id/auditAudit events for a specific document/v1/analyticsAggregated analytics: views/day, top docs, denial reasonsEmbeddable Viewer
Drop the embed script into any webpage to render a PhantomDocs viewer inline — no iframes to configure manually.
/embed.jsEmbeddable viewer widget scriptEmbed widget usage
Add the script once, then drop viewer elements anywhere:
<!-- 1. Load the widget script once --> <script src="http://localhost:5001/embed.js"></script> <!-- 2. Place viewer elements wherever you like --> <div data-phantom-doc="your-document-id" data-token="your-access-token" data-height="700px" ></div>
The script auto-initialises on DOM-ready and watches for dynamically added elements. Attributes: data-phantom-doc (required), data-token (required),data-height (default: 600px), data-radius (border-radius, default: 10px).
Webhook payload format
Every delivery POSTs JSON with this envelope:
{
"id": "uuid", // unique delivery ID
"event": "document.viewed",
"createdAt": "2026-04-18T10:00:00.000Z",
"data": {
"documentId": "...",
"accessToken": "...",
"ip": "1.2.3.4",
"userAgent": "Mozilla/5.0..."
}
}Verify authenticity using the X-PhantomDocs-Signature header (HMAC-SHA256 of the raw body with your webhook secret).