Typed clients and LLM access

The OpenAPI document is the contract: everything the API accepts and returns, generated from the running code and published at api.affiliaterail.com/v1/openapi.json. Anything that can consume OpenAPI 3.1 can consume it, which means you rarely need to write request types by hand.

A typed TypeScript client

The pairing we use ourselves is openapi-typescript for the types and openapi-fetch for the calls: a thin, fully typed fetch wrapper with no codegen beyond one .d.ts file.

npm install openapi-fetch
npm install -D openapi-typescript
npx openapi-typescript https://api.affiliaterail.com/v1/openapi.json -o rail-api.d.ts

import createClient from "openapi-fetch";
import type { paths } from "./rail-api";

const rail = createClient<paths>({
  baseUrl: "https://api.affiliaterail.com",
  headers: { Authorization: `Bearer ${process.env.RAIL_API_KEY}` },
});

const { data, error } = await rail.GET("/v1/partners", {
  params: { query: { program_id: "prg_...", limit: 5 } },
});
// data is typed: { data: Partner[]; has_more: boolean; total_count: number }

Every path, parameter and response body is typed from the same document the interactive reference renders, so your compiler and the docs can never disagree. Rerun the generate command whenever you want to pick up new endpoints; additive changes never break existing calls.

The same document feeds generators for other languages (any OpenAPI 3.1 toolchain), and it validates: the published copy is checked against the spec schema on every build of ours.

LLM access

If a model is reading, skip HTML entirely:

• api.affiliaterail.com/llms.txt: the index, one screen, with links to everything else.
• api.affiliaterail.com/llms-full.txt: every route, parameter and schema as plain text.
• app.affiliaterail.com/webhooks/llms.txt: the webhook event catalogue with payload examples and signature verification.
• docs.affiliaterail.com/llms.txt: this documentation suite as a page list.

Paste one into a prompt, or point a coding assistant at it, and it has the exact contract rather than a guess.

If the assistant should read your data rather than the API's shape, that is what the MCP server is for: a live, scoped, revocable connection to your own program.