OpenAPI and Postman

The whole Referalli API is described in one OpenAPI 3.1 document: 410 operations across 28 tags, every request and response schema, every error response, and the 33 webhook topics with a payload schema and sample for each. The official SDKs and this site's API reference are generated from it.

The live document is public (no key needed) and always matches the API that serves it. Each tagged release of referalli-openapi attaches the spec and the Postman collection as release files, so you can pin the exact copy you generated code from. The document's info.version is the API version it describes (2026-11-01).

Postman

1. Download postman_collection.json from referalli-openapi, then choose Import in Postman.

2. Set the collection variable apiKey to a test key (rk_test_...) from Settings → API keys.

3. baseUrl defaults to https://referalli.com. Change it to http://localhost:4000 for a local API.

The collection has one folder per tag and one request per operation, authenticated with Authorization: Bearer {{apiKey}}.

You can also import the live spec directly: Import → Link and paste https://referalli.com/v1/openapi.json.

Generate a client

An official SDK already exists for JavaScript, Python, Ruby, Go, PHP, Swift and Kotlin, with retries, idempotency, pagination and webhook verification built in. For any other language, point a generator at the spec:

# TypeScript types only
npx openapi-typescript https://referalli.com/v1/openapi.json -o referalli.d.ts

# A client in another language, for example C#
npx @openapitools/openapi-generator-cli generate \
  -i https://referalli.com/v1/openapi.json -g csharp -o ./referalli-csharp

Generated clients should send:

• Authorization: Bearer rk_... (the apiKey security scheme);

• Referalli-Version: 2026-11-01, to pin the version you generated against;

• an Idempotency-Key on every POST, reused across retries.

See Errors and limits for the error envelope and the retry rules.

What the document contains

• paths: every /v1 operation. Each has an operationId (the SDK method names come from it), a summary, the scope it needs, its parameters and request body, and typed responses, including the error responses it can return.

• components.schemas: every model (Program, Partner, Referral, CommissionEvent, Payout, …).

• components.securitySchemes: apiKey (server-side bearer keys), session (the dashboard cookie) and partnerSession (the partner portal).

• webhooks: one entry per event topic, with the delivery envelope and the topic's data schema.

Use it with AI tools

Agent frameworks that load tools from OpenAPI can use the live document directly. For Claude, Cursor and other MCP clients, the MCP server is the simpler route, and it asks for confirmation before any write. /llms.txt lists these docs for language models.