> ## Documentation Index
> Fetch the complete documentation index at: https://docs.formepdf.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Documents

> How the Forme Documents archive works — automatic saving, source types, metadata, retention, and download URLs.

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:

```json theme={null}
{
  "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:

```bash theme={null}
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](/api-reference/render#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:

```bash theme={null}
curl https://api.formepdf.com/v1/documents/clxyz... \
  -H "Authorization: Bearer forme_sk_abc123..."
```

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

***

## Listing Documents

See [Render API — Resources](/api-reference/render#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](/concepts/audit-trail) for details.

***

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