OpenAPI for QR generation

UseQR's full API surface is described in an OpenAPI 3.1 document at https://useqr.app/api/openapi.json: generate, typed payloads, batch, decode and verify. It declares no security schemes, so it imports into GPT Actions with authentication set to None and generates typed clients with tools like openapi-typescript without any auth plumbing.

One document, three consumers

/api/openapi.json is the machine-readable contract for the whole keyless API: the generate endpoint with every styling parameter, the typed payload endpoints, batch, decode and verify. It is OpenAPI 3.1.0, and it exists for three distinct consumers:

Code generators, produce a typed client instead of hand-writing fetch calls.
Agent platforms, GPT Actions and MCP-adjacent tooling import the spec as a tool definition.
Humans skimming: parameter names, enums and examples in one place, without reading prose docs.

The design decision that shapes all three: the document declares no security schemes. That is not an omission: there is no authentication to describe. Every downstream artefact inherits the simplification: generated clients have no token constructor argument, Actions import with authentication preset to None, and no example in any README starts with "first, export your API key".

Generating a typed client

npx openapi-typescript https://useqr.app/api/openapi.json -o useqr.d.ts

import type { paths } from "./useqr";

type QrParams = paths["/api/v1/qr"]["get"]["parameters"]["query"];
// data: string; size?: number; format?: "png" | "svg" | ...; ec?: "L" | "M" | "Q" | "H"; ...

Now parameter names, enum values (module styles, eye shapes, EC levels) and the batch request shape are compiler-checked, a typo in style= fails your build instead of producing a runtime 400. Heavier generators (openapi-generator, Kiota and friends) work the same way and need no auth configuration for the same reason. The response schemas are worth generating too: the verify report ({scannable, decoded, matchesInput, version, ecLevel, contrast, issues}) and the batch envelope ({count, ok, failed, results}) are stable shapes your code can switch on.

As a GPT Action or agent tool

Import the URL in a custom GPT's Actions panel and the entire surface becomes callable by the model: the two-minute walkthrough is on the ChatGPT page. For MCP-native clients, the same capabilities are pre-wrapped as tools by the MCP server; OpenAPI is the right surface when the platform speaks REST tool definitions rather than MCP.

Two spec details written for model consumers rather than humans: descriptions state the parameter aliases (data/text/content/url all name the payload), so a model that guesses wrong still guesses right; and the error response is documented as application/problem+json with its fix field, which tells the model that a 400 contains a corrected call worth retrying, the design reasoning.

Contract stability

A spec is only as useful as its stability. The one this document describes: v1 endpoint shapes never break: parameters are only ever added, never renamed or removed. So a client generated today keeps compiling against next year's spec, and hardcoding a URL built from the spec is safe. Pin a copy of the JSON in your repo if your build must be hermetic; regenerate when you want new parameters, not because anything expired.

Determinism completes the contract: the spec describes pure GET endpoints whose responses are cacheable forever, which means a generated client needs no retry-with-backoff sophistication: a failed call is safe to retry, a repeated call is free.

FAQ

Where is the UseQR OpenAPI spec?

At https://useqr.app/api/openapi.json, an OpenAPI 3.1 document covering generation, typed payload endpoints, batch, decode and verify, with parameter enums and problem+json error shapes included.

Why does the spec declare no security schemes?

Because the API has no authentication, no key, no signup, no quota. Declaring nothing is the accurate description, and it means GPT Actions import with auth set to None and generated clients need no credential plumbing.

How do I generate a TypeScript client for the QR API?

Run npx openapi-typescript https://useqr.app/api/openapi.json -o useqr.d.ts and import the paths types. Query parameters, style enums and response shapes become compile-time checked with no runtime dependency.

Will a generated client break when the API changes?

The stability contract says v1 shapes never break and parameters are only added, so existing generated clients keep working. Regenerate when you want newly added parameters, and pin the spec file if your build must be reproducible.