API Registry

OpenAPI 3.1 specification management -- versioning, CI validation, snapshots, and SDK generation

The RevKeen API Registry is the canonical source for the OpenAPI specification that powers the entire developer platform. The interactive docs, SDKs, mock server, and MCP schemas are all generated from a single spec.

Specification

The RevKeen API is described by an OpenAPI 3.1 specification generated dynamically from the engine-api routes.

Asset	URL	Format
Production Spec	`api.revkeen.com/v2/openapi.json`	OpenAPI 3.1 JSON
Sandbox Spec	`sandbox-api.revkeen.com/v2/openapi.json`	OpenAPI 3.1 JSON
Interactive Docs	`/api-reference/openapi`	Scalar UI with env toggle

The spec is generated at build time from Hono route definitions using @hono/zod-openapi. Every route, schema, and security requirement is derived from the source code -- not maintained as a separate document.

What the Registry Powers

The OpenAPI specification is the single input that generates six developer tools:

Tool	Generated From Spec	How
Interactive API Docs	Endpoints, schemas, examples	Scalar renders the spec as a three-pane reference
TypeScript SDK	Operations, types, error codes	Fern generates `@revkeen/sdk` from the spec
Python SDK	Operations, types, error codes	Fern generates `revkeen` PyPI package
PHP SDK	Operations, types, error codes	Fern generates `revkeen/revkeen-php`
Mock Server	Schemas, examples, enums	Scalar CLI generates mock responses from the spec
MCP Tool Schemas	Endpoints, parameters, responses	MCP server derives tool definitions from route schemas

Versioning

The API uses date-based versioning following the Stripe model. The current API version is embedded in the spec as the info.version field.

URL-based routing -- All endpoints are prefixed with /v2/
Non-breaking additions -- New fields, new endpoints, and new enum values are added to /v2/ without a version bump
Breaking changes -- Removing fields, changing types, or removing endpoints will result in a new URL prefix (/v3/)
Deprecation policy -- Deprecated endpoints are announced at least 6 months before removal

CI Validation Pipeline

Every pull request that modifies API routes triggers automated validation:

Lint

Redocly linting enforces Stripe-grade quality rules:

Every operation must have an operationId
Every operation must be tagged
Every endpoint must declare a security scheme
Request and response schemas must use $ref for reusable types
Descriptions are required on all parameters and properties

Breaking Change Detection

oasdiff compares the new spec against the previous version and flags:

Removed endpoints or operations
Removed or renamed request/response fields
Changed field types or formats
Removed enum values
Tightened validation (new required fields)

Breaking changes block the PR until explicitly approved.

Custom Validation

A custom validator checks RevKeen-specific conventions:

Consistent error response format across all endpoints
Pagination parameters on all list endpoints
Idempotency key support on all financial mutations
Standard sort and filter query parameters

Snapshot

On merge to main, a dated snapshot is saved to packages/openapi/snapshots/ for changelog generation and rollback reference.

Snapshots and Changelog

Dated snapshots of the specification are stored after each release:

packages/openapi/snapshots/
  2026-03-15.json
  2026-03-01.json
  2026-02-15.json
  ...

Changelog generation:

# Compare two snapshot dates
pnpm --filter @revkeen/openapi changelog 2026-03-01 2026-03-15

This produces a human-readable changelog of added, changed, and removed endpoints and schemas.

Diff commands:

# Show all changes
pnpm --filter @revkeen/openapi diff

# Show only breaking changes
pnpm --filter @revkeen/openapi diff:breaking

Downloading the Spec

The spec is available for import into any OpenAPI-compatible tool.

Direct download:

curl -o revkeen-openapi.json https://api.revkeen.com/v2/openapi.json

Import into tools:

Tool	Method
Postman	Import > Link > paste spec URL
Insomnia	Import/Export > From URL > paste spec URL
Scalar API Client	Open client.scalar.com > paste spec URL
Stoplight	Add API > Import OpenAPI > paste spec URL
SwaggerUI	Set `url` config to the spec URL

SDK Generation

SDKs are generated from the spec using Fern:

# Generate all SDKs
pnpm --filter @revkeen/openapi generate

# Generate a specific language
fern generate --group typescript
fern generate --group python
fern generate --group php

The Fern configuration lives at fern/generators.yml and reads the canonical spec from packages/openapi/openapi.json.

Spec-first development

The OpenAPI spec is the contract between the API and its consumers. SDK types, mock responses, and documentation are all derived from it. If the spec is wrong, everything downstream is wrong. That is why every change goes through CI validation.

Local Development

Fetch the latest spec from any environment:

# From production
pnpm --filter @revkeen/openapi fetch

# From staging
pnpm --filter @revkeen/openapi fetch:staging

# From local dev server
pnpm --filter @revkeen/openapi fetch:local

Run the mock server locally:

pnpm --filter @revkeen/openapi mock
# Starts on http://localhost:4010

Validate locally before pushing:

pnpm --filter @revkeen/openapi lint
pnpm --filter @revkeen/openapi validate