Documents

Every PDF that Forme produces or processes is saved to the Documents archive. This gives you a searchable history of all renders, redactions, merges, and certifications — with download URLs, metadata filtering, and audit trails.

How Documents Are Created

Action	Source	Automatic?
API render (`POST /v1/render/:slug`)	`generated`	Yes (opt out with `save: false`)
Manual upload in dashboard	`uploaded`	Yes
Redaction (`POST /v1/redact`)	`redacted`	Yes
Merge (`POST /v1/merge`)	`merged`	Yes
Certification (`POST /v1/certify`)	`certified`	Yes

Controlling Save Behavior

By default, every sync render saves the PDF as a document. You can control this with two fields in the render request body:

save: false — skip saving entirely (useful for previews or ephemeral renders)
saveName: "Q1 Report" — custom document name instead of the default {slug}-{YYYY-MM-DD}

Metadata

Tag documents with your own key-value pairs for organization and retrieval:

{
  "clientName": "Jane Smith",
  "metadata": {
    "customerId": "cust_123",
    "department": "billing"
  }
}

Developer metadata is merged with system metadata (renderTimeMs, templateSlug) on the document record.

Filtering

Query documents by metadata values using metadata.* query parameters:

curl "https://api.formepdf.com/v1/documents?metadata.customerId=cust_123" \
  -H "Authorization: Bearer forme_sk_abc123..."

Multiple filters are ANDed together (maximum 5 per request). See Render API — Metadata for limits.

Retention

Documents are retained based on your plan:

Plan	Retention
Free	30 days
Pro	90 days
Team	1 year
Business	Unlimited

After the retention period, documents and their stored PDFs are permanently deleted.

Storage

PDFs are stored in Cloudflare R2 (S3-compatible). The storageKey is server-side only and never exposed to the frontend.

Download URLs

Retrieve a document by ID to get a presigned download URL with 1-hour expiry:

curl https://api.formepdf.com/v1/documents/clxyz... \
  -H "Authorization: Bearer forme_sk_abc123..."

{
  "data": {
    "id": "clxyz...",
    "name": "invoice-2024-01-15",
    "source": "generated",
    "downloadUrl": "https://..."
  }
}

Listing Documents

See Render API — Resources for the full listing API with pagination, source filtering, date ranges, and metadata queries.

Audit Trail

Every operation on a document is logged — who did what, when, and how (dashboard or API key). See Audit Trail for details.

Documents are a hosted API feature. Self-hosted instances have no storage layer — PDFs are returned directly and not persisted.

Getting Started

Reference

API Reference

Concepts

Enterprise

SDKs

Guides

Changelog

How Documents Are Created

Controlling Save Behavior

Metadata

Filtering

Retention

Storage

Download URLs

Listing Documents

Audit Trail

​How Documents Are Created

​Controlling Save Behavior

​Metadata

​Filtering

​Retention

​Storage

​Download URLs

​Listing Documents

​Audit Trail

How Documents Are Created

Controlling Save Behavior

Metadata

Filtering

Retention

Storage

Download URLs

Listing Documents

Audit Trail