Generate a client

The API describes itself at api.rollful.dev/openapi.json, an OpenAPI 3.1 document. Point a generator at that URL and you get a client without writing one.

Fetch the document

curl https://api.rollful.dev/openapi.json > rollful.json

The document is generated from the same schemas that validate incoming requests, so it cannot describe an API this one does not serve. Its info.version is the build that answered you; Versioning explains how that relates to /v1.

Generate a typed client

The document uses nothing exotic — no callbacks, no webhooks, no polymorphic bodies — so any generator that reads OpenAPI 3.1 will handle it.

# TypeScript types only
npx openapi-typescript https://api.rollful.dev/openapi.json -o rollful.d.ts

# A full client, in whichever language
npx @openapitools/openapi-generator-cli generate \
  -i https://api.rollful.dev/openapi.json \
  -g python \
  -o ./rollful-client

Generators that only speak OpenAPI 3.0 may refuse the document or mistranslate its schemas. If yours does, downconvert it first rather than hand-editing the result.

Narrow your error handling

Each status has its own schema listing only the codes that status can carry, rather than one shared error shape everywhere. A generated client can therefore narrow: a 429 is rate_limited and nothing else, while a 400 is one of three codes.

Treat a code you do not recognise as a plain failure of its status rather than an unreachable branch — the set can grow within /v1.

Import it into a tool

The same URL works anywhere that reads OpenAPI: Postman, Insomnia, Bruno, a REST client in your editor. Import by URL rather than by file so a new deploy updates what you have.

The rendered version of the same document is the endpoint reference, which carries a ready-made snippet per operation in every language it can generate.

Where to go next

• Errors — the codes your generated client will narrow on.
• Versioning — what stays stable while you depend on it.