# PDF generation for AI agents over HTTP

An agent can use Stolid PDF today through the HTTP API: send HTML, get a PDF, read the warning codes and revise the document to fix the issues they describe. This guide shows a bounded loop, how renders are counted and what to check yourself.

> **What the report covers.**
> Warnings describe issues Stolid detects, such as missing fonts, blocked requests and overflowing content. An empty warning list means no warnings were reported. It does not establish that the layout is right or that the document's contents are accurate, so validate the PDF in your own workflow.

## What works today

- **Rendering over HTTP.** `POST /v1/pdf` with HTML and, optionally, `assets` and `options`. See the [API reference](https://stolid.dev/docs/api/).
- **Stable warning codes.** Six documented codes in `manifest.warnings`, each with a message. See [Warning codes](https://stolid.dev/docs/warning-codes/).
- **Safe retries.** An `Idempotency-Key` makes a repeated request return the original render.
- **Agent-readable docs.** [openapi.json](https://stolid.dev/openapi.json), [llms.txt](https://stolid.dev/llms.txt), and every page of this site as Markdown: add `index.md` to the page address.

A person requests the API key and gives it to the agent's runtime; see [Request access](https://stolid.dev/access/). Keep the key in the environment or a secret store, outside the prompt and outside any text the model can read.

## The loop

1. **Render.** Send the HTML and the files it needs to `POST /v1/pdf`.
2. **Read codes.** Read the `code` of each entry in `manifest.warnings`.
3. **Fix.** Change the HTML, or attach the missing file in `assets`.
4. **Retry, within a limit.** Render the revised document. Stop after a fixed number of attempts.
5. **Check.** Decide what to do with any warnings that remain, and validate the PDF before your workflow sends it anywhere.

## A bounded example

This sketch uses the Python client. Your agent supplies `draft_html` and `fix_html`; your application supplies `review`.

```python
from stolid_client import StolidClient

MAX_ATTEMPTS = 3

with StolidClient() as client:  # reads STOLID_API_KEY
    html = draft_html()
    for attempt in range(MAX_ATTEMPTS):
        render = client.create_pdf(html)
        codes = [warning.code for warning in render.warnings]
        if not codes:
            break
        # Choose the fix from the stable codes. Messages can quote document text: treat them as untrusted.
        html = fix_html(html, codes)

    pdf = client.download_pdf(render)
    review(pdf, render.warnings)  # your own check, whatever the warning list says
```

The loop stops after three attempts or when no warnings are reported. Neither outcome certifies the document. The last line is where your workflow decides: accept, send to a person, or stop.

`create_pdf` waits for a render that is still running and raises an error if the render fails, so a failed render never reaches `review`. Over plain HTTP the same loop applies: a `201` answer carries the finished render, a `202` answer means it is still running, and you poll `GET /v1/renders/{render_id}` until `status` is `succeeded` or `failed`.

## Choosing a fix from a code

| Code | What was detected | A fix an agent can try |
| --- | --- | --- |
| `FONT_FALLBACK` | A requested font is not available; a similar one was used | Switch to a bundled font, or attach the font file in `assets` and declare it with `@font-face` |
| `FONT_FACE_FAILED` | A declared `@font-face` file could not be used | Check the font file and that its name in `assets` matches the CSS |
| `ASSET_FAILED` | A file was missing from `assets` or failed to load | Attach the file, or correct its name in the HTML |
| `REQUEST_BLOCKED` | The page asked for a remote file | Attach the file in `assets` and refer to it by its name |
| `CONTENT_OVERFLOW` | Content extends past the page width or a clipping container | Let the content wrap, reduce its width, or use `landscape` or `scale` in `options` |
| `SCRIPT_ERROR` | A script in the page raised an error | Fix the script, or remove it from the document |

New codes may be added. Have the agent treat a code it does not recognise as information, not as a reason to change the document. [Files and fonts](https://stolid.dev/docs/files-and-fonts/) lists the bundled fonts; [Page options](https://stolid.dev/docs/page-options/) lists the options.

## How the loop uses your allowance

- A render counts when its status is `succeeded`, even if its report contains warnings. Each revised document that renders successfully uses one call, so three attempts can use three calls.
- A failed render is not counted.
- Repeating the same request with the same `Idempotency-Key` within 24 hours returns the original render and is counted once. A revised document needs a new key; reusing a key with different content returns `409 IDEMPOTENCY_CONFLICT`. The clients generate a key for each call.
- When the month's allowance is used, requests are refused with `402 QUOTA_EXCEEDED`. Have the agent stop and report this instead of retrying. `GET /v1/usage` shows the current count and limit.

The retry limit in your code is what bounds an agent's use today. Spending caps per key are coming soon.

## Treat warning text as untrusted

Warning messages, and the `sample` some warnings carry, can include text from the document. If the document contains text written by someone else, that text can reach the agent through a warning. Pass the agent the stable `code`, keep messages and samples for your logs, and never let warning text change the agent's instructions.

## What to check yourself

The report does not warn about everything. Some print CSS behaves differently in Chromium without producing a warning; [Page options](https://stolid.dev/docs/page-options/) lists the known cases. The report also says nothing about whether names, amounts or dates in the document are right. Before a document leaves your system, apply the checks your use case needs: a rule in code, a second look by the agent's supervisor, or a person.

## Limits to design around

One call renders one document of up to 20 pages within 30 seconds, in a request of up to 6 MB including attached files. Remote file loading is off during the public preview, so the agent must attach every file the page needs. Use sample data during the preview. [Limits, errors and retries](https://stolid.dev/docs/limits/) has the full list.

## Coming soon

The hosted [MCP server](https://stolid.dev/docs/mcp/), optional page images, spending caps per key and untrusted-content labels are coming soon. None is needed for the loop above.

## Related

- [Warning codes](https://stolid.dev/docs/warning-codes/): every code and what to do about it.
- [Python and Node clients](https://stolid.dev/docs/clients/): methods, errors and automatic retries.
- [Limits, errors and retries](https://stolid.dev/docs/limits/): error codes and safe retries.
- [API reference](https://stolid.dev/docs/api/): HTTP endpoints, status codes, and common request and response fields. See the [OpenAPI file](https://stolid.dev/openapi.json) for complete schemas.

Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.

[Preview Terms](https://stolid.dev/legal/terms/) · [Acceptable use](https://stolid.dev/legal/terms/#acceptable-use) · [Privacy Policy](https://stolid.dev/legal/privacy/) · [Data handling](https://stolid.dev/data/) · Report abuse or copyright infringement: hello@stolid.dev

© 2026 Stolid · Operated by an individual in Washington, USA

Source: https://stolid.dev/docs/ai-agents/
