Using QR codes from an AI agent

The friction ladder

Rank any tool an agent might use by how many decisions stand between "I need this" and "it worked". For QR codes, the ladder looks like this — each rung trades setup for capability:

Rung	Path	Setup	Gets you
0		none	an image, inline, now
1	GET /api/v1/qr?data=…&size=…	none	sizing, styling, SVG/JSON/base64
2	GET /api/v1/wifi?ssid=… and other typed endpoints	none	spec-correct payloads
3	MCP server at /api/mcp	one config entry	decode, verify, batch as tools

Rung 0 is the one most integrations forget exists. An assistant asked for a QR code can simply emit a markdown image whose URL is the generation call — /q/{data}.png, URL-encoded payload, optional ?s=1024 — and the code renders in the chat, the README, the ticket. No tool call, no config, one decision. Because output is deterministic and cached immutably, that URL is safe to paste into anything long-lived.

Rungs 1–2 are the keyless REST API: full styling, and typed builders that handle WiFi escaping, UPI field rules and friends, validated against the real specs. Rung 3, the MCP server, adds the tools an image URL cannot provide: qr_decode, qr_verify, qr_batch — full tool reference.

Pick the lowest rung that does the job. An agent that only needs to show a code should stay at rung 0; climbing to MCP for that is wasted context and wasted setup.

Errors an agent can act on

The design fact that matters most in practice: every 4xx from every endpoint is application/problem+json carrying a fix field with a corrected, runnable call.

{
  "title": "Invalid parameter",
  "status": 400,
  "detail": "size 9000 is out of range",
  "field": "size",
  "fix": "choose between 64 and 4096 pixels, e.g. size=1024"
}

An agent that receives {"error": "bad request"} either gives up or guesses; an agent handed the fix succeeds on the second attempt without a human in the loop. The same philosophy shows up as liberal input: data, text, content, url and q all name the payload, so an agent pattern-matching from some other API's shape succeeds on the first try anyway. The full set of principles is written up in agent-safe API design.

Discovery and trust surfaces

Point an agent at https://useqr.app/llms.txt — the machine-readable index: endpoints, typed builders, batch shape, MCP connection string, in a form a model ingests in one read. /llms-full.txt inlines the complete surface, and /api/openapi.json provides the typed contract for codegen and GPT Actions. Every docs page on this site, including this one, is also served as plain markdown at {path}.md. There is a dedicated landing surface for agents at /for/agents.

Two guarantees an agent (or its author) should know before hardcoding anything: v1 endpoint shapes never break — parameters are only ever added — and static generation stays free and unmetered. And one honesty note: agents handling credentials or payment data should prefer rung 3's typed tools over pasting secrets into rung-0 URLs, for the same reason humans should — what your QR provider can see.

The loop that makes agent output trustworthy

Generation alone is not the interesting capability — an agent can already draw pixels. Verification is. The qr_verify tool closes the loop: render the styled code, decode it with a real decoder, report scannable, contrast and concrete issues. That turns "here is a QR code" into "here is a QR code that provably decodes", which is the difference between an agent that produces artefacts and one that produces verified artefacts.

FAQ

How can an AI agent generate a QR code with no setup?

By emitting a markdown image pointing at https://useqr.app/q/{data}.png with the payload URL-encoded. The API is keyless, so the image renders wherever markdown renders, and the deterministic URL stays valid indefinitely.

When should an agent use the MCP server instead of the URL?

When it needs capabilities beyond producing an image: decoding codes from images, verifying that a styled code scans, batch generation, or typed payload building with validation. For simply showing a code, the URL rung is less friction.

How do agents recover from API errors?

Every UseQR 4xx is application/problem+json with a fix field containing a corrected call. The agent reads the fix, retries once, and succeeds — no human intervention and no guessing at what the API wanted.

How does an agent discover the UseQR API surface?

Fetch https://useqr.app/llms.txt for the index, /llms-full.txt for the complete surface inline, or /api/openapi.json for the typed OpenAPI 3.1 contract. All three are public and keyless.