> ## 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 hosted API saves rendered PDFs to Documents — what is saved, metadata, retention per plan, and download URLs.

**Documents** is the archive of PDFs in your hosted account. API renders are saved there automatically, and you can work on saved documents in the Dashboard's Document Editor (redact, certify, merge).

***

## How documents are created

| Action | `source` | Saved |
| - | - | - |
| `POST /v1/render/:slug` | `generated` | Yes, by default. Opt out with `save: false`. |
| `POST /v1/render/html` | `generated` | Yes, by default. Opt out with `save: false`. |
| Upload in the Dashboard | `uploaded` | Yes |
| Redact, merge, or certify in the Dashboard's Document Editor | `redacted`, `merged`, `certified` | Yes |
| `POST /v1/render/:slug/async` | — | No. The PDF is in the job result. |
| `POST /v1/redact`, `/v1/merge`, `/v1/certify` | — | No. The PDF is returned in the response only. |

### Save options on sync renders

* `save: false` — do not save.
* `saveName: "Q1 Report"` — the document name. Default: `{slug}-YYYY-MM-DD` for templates, `html-YYYY-MM-DD` for `/v1/render/html`.
* `metadata` — your own key-value pairs (paid plans). See [Metadata](https://docs.formepdf.com/hosted-api/render.md#metadata).

The save happens after the response is sent. A render response does not include the document ID. Find the document with [`GET /v1/documents`](https://docs.formepdf.com/hosted-api/resources#documents), for example by a `metadata` value you set.

***

## Metadata

Each saved render has system metadata: `renderTimeMs`, plus `templateSlug` (template renders) or `input: "html"` (`/v1/render/html`). Your `metadata` keys are merged into the same object.

```json theme={null}
{
  "renderTimeMs": 84,
  "templateSlug": "invoice",
  "customerId": "cust_123",
  "department": "billing"
}
```

Filter by your keys with `metadata.<key>` query parameters on [`GET /v1/documents`](https://docs.formepdf.com/hosted-api/resources#documents).

***

## Retention

When a document is saved, it gets an expiry date (`expiresAt`) from the account's plan at that time:

| Plan | Retention |
| - | - |
| Free | 7 days |
| Starter | 90 days |
| Pro | 365 days |
| Business | No expiry (`expiresAt: null`) |

After `expiresAt`, the document and its PDF are permanently deleted. The deletion can happen some time after `expiresAt`, so do not rely on a document being gone at an exact time. Changing plans does not change the expiry of documents that are already saved. See the **Billing** page in the Dashboard for current plan details.

> [!TIP]
>
> To keep PDFs beyond the retention period, store them yourself: use the response bytes, the [`s3`](https://docs.formepdf.com/hosted-api/render#s3-upload) option, or download them with `downloadUrl`.

***

## Download URLs

[`GET /v1/documents/:id`](https://docs.formepdf.com/hosted-api/resources#documents) returns a `downloadUrl`. It is a signed URL that expires 1 hour after the request. Ask again for a new URL. The storage location of the PDF itself is never returned.

***

## Audit trail

Actions on a document are logged: who did what, when, and from where (Dashboard or API key). See [Audit Trail](https://docs.formepdf.com/hosted-api/audit-trail.md).

***

> [!NOTE]
>
> Documents are a hosted API feature. The [self-hosted server](https://docs.formepdf.com/self-hosting.md) has no storage: it returns the PDF and keeps nothing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.