Docs / Agents / PDF generation for AI agents over HTTP

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/pdf with HTML and, optionally, assets and options. See the API reference.
  • Stable warning codes. Six documented codes in manifest.warnings, each with a message. See Warning codes.
  • Safe retries. An Idempotency-Key makes a repeated request return the original render.
  • Agent-readable docs. openapi.json, 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. 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

CodeWhat was detectedA fix an agent can try
FONT_FALLBACKA requested font is not available; a similar one was usedSwitch to a bundled font, or attach the font file in assets and declare it with @font-face
FONT_FACE_FAILEDA declared @font-face file could not be usedCheck the font file and that its name in assets matches the CSS
ASSET_FAILEDA file was missing from assets or failed to loadAttach the file, or correct its name in the HTML
REQUEST_BLOCKEDThe page asked for a remote fileAttach the file in assets and refer to it by its name
CONTENT_OVERFLOWContent extends past the page width or a clipping containerLet the content wrap, reduce its width, or use landscape or scale in options
SCRIPT_ERRORA script in the page raised an errorFix 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-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 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.

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