Docs menu · PDF generation for AI agents over HTTP
Agents
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/pdfwith HTML and, optionally,assetsandoptions. See the API reference. - Stable warning codes. Six documented codes in
manifest.warnings, each with a message. See Warning codes. - Safe retries. An
Idempotency-Keymakes a repeated request return the original render. - Agent-readable docs. openapi.json, llms.txt, and every page of this site as Markdown: add
index.mdto the page address.
A person requests the API key and gives it to the agent's runtime; see Request access. Keep the key in the environment or a secret store, outside the prompt and outside any text the model can read.
The loop
- Render. Send the HTML and the files it needs to
POST /v1/pdf. - Read codes. Read the
codeof each entry inmanifest.warnings. - Fix. Change the HTML, or attach the missing file in
assets. - Retry, within a limit. Render the revised document. Stop after a fixed number of attempts.
- 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.
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 lists the bundled fonts; 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-Keywithin 24 hours returns the original render and is counted once. A revised document needs a new key; reusing a key with different content returns409 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/usageshows 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 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 has the full list.
Coming soon
The hosted MCP server, optional page images, spending caps per key and untrusted-content labels are coming soon. None is needed for the loop above.
Related
- Warning codes: every code and what to do about it.
- Python and Node clients: methods, errors and automatic retries.
- Limits, errors and retries: error codes and safe retries.
- API reference: HTTP endpoints, status codes, and common request and response fields. See the OpenAPI file for complete schemas.
Public preview: free while we work with early users. Use sample data; there is no uptime commitment yet.