OpenAPI Specification

The full Rhumby API is described by an OpenAPI 3.1 specification.

Spec URL

GET /api/v1/openapi

Returns the complete OpenAPI 3.1.0 specification in JSON format.

Download

openapi.json — OpenAPI 3.1.0 specification

What's Included

The OpenAPI spec provides:

All 14 API endpoints with complete request/response schemas
Authentication via Bearer token (API keys)
Pagination schemas (limit, offset, hasMore)
All data models (Event, Organization, Registration, Result, etc.)
Error response formats (401, 400, 404, 500)
Query parameters with types, defaults, and validation rules
Required vs optional fields
Enum values for status fields

SDK Generation

Generate a type-safe client in any language using OpenAPI generators:

TypeScript

# Using OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://rhumby.com/openapi.json \
  -g typescript-fetch \
  -o ./rhumby-sdk

# Using openapi-typescript
npx openapi-typescript https://rhumby.com/openapi.json -o rhumby-types.ts

Python

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g python \
  -o ./rhumby-sdk

Go

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g go \
  -o ./rhumby-sdk

Ruby

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g ruby \
  -o ./rhumby-sdk

API Testing Tools

Import the spec into your favorite API testing tool:

Postman: Import > Link > https://rhumby.com/openapi.json
Insomnia: Import > From URL > https://rhumby.com/openapi.json
Swagger UI: Point to https://rhumby.com/openapi.json
Bruno: Import > OpenAPI > https://rhumby.com/openapi.json

Validation

Use the spec to validate your requests and responses:

import Ajv from 'ajv';
import spec from './openapi.json';

const ajv = new Ajv();
const validate = ajv.compile(spec.components.schemas.Event);

if (!validate(eventData)) {
  console.error('Invalid event:', validate.errors);
}

Documentation Generation

Generate interactive documentation:

# Redoc
npx @redocly/cli build-docs openapi.json -o docs.html

# Swagger UI
docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.json \
  -v $(pwd)/public:/usr/share/nginx/html \
  swaggerapi/swagger-ui

Mock Server

Create a mock API server for testing:

# Prism
npx @stoplight/prism-cli mock openapi.json

# MSW (Mock Service Worker)
npx msw init public/ --save

Example Usage

Once you've generated a client:

import { Configuration, EventsApi } from './rhumby-sdk';

const config = new Configuration({
  basePath: 'https://api.rhumby.com',
  headers: {
    Authorization: 'Bearer rhb_your_api_key_here'
  }
});

const api = new EventsApi(config);

// List upcoming events
const events = await api.listEvents({
  status: 'published',
  after: '2026-03-01',
  limit: 10
});

// Get event details with fleets
const event = await api.getEvent({
  slug: 'spring-series-2026',
  include: 'fleets,races'
});

// Register for an event
const registration = await api.registerForEvent({
  slug: 'spring-series-2026',
  registrationRequest: {
    fleetId: 'fleet-uuid',
    boatId: 'my-boat-uuid',
    crew: ['Alice', 'Bob']
  }
});

Staying in Sync

The OpenAPI spec is automatically updated when API routes change. To ensure you're always using the latest:

Subscribe to Rhumby API changelog at https://rhumby.com/changelog
Watch the GitHub repository for releases
Set up CI to regenerate your SDK on new spec versions

Contributing

Found an error in the spec? Report it at https://github.com/rhumby/api-issues

The full Rhumby API is described by an OpenAPI 3.1 specification.

Spec URL

GET /api/v1/openapi

Returns the complete OpenAPI 3.1.0 specification in JSON format.

Download

openapi.json — OpenAPI 3.1.0 specification

What's Included

The OpenAPI spec provides:

All 14 API endpoints with complete request/response schemas
Authentication via Bearer token (API keys)
Pagination schemas (limit, offset, hasMore)
All data models (Event, Organization, Registration, Result, etc.)
Error response formats (401, 400, 404, 500)
Query parameters with types, defaults, and validation rules
Required vs optional fields
Enum values for status fields

SDK Generation

Generate a type-safe client in any language using OpenAPI generators:

TypeScript

# Using OpenAPI Generator
npx @openapitools/openapi-generator-cli generate \
  -i https://rhumby.com/openapi.json \
  -g typescript-fetch \
  -o ./rhumby-sdk

# Using openapi-typescript
npx openapi-typescript https://rhumby.com/openapi.json -o rhumby-types.ts

Python

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g python \
  -o ./rhumby-sdk

Go

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g go \
  -o ./rhumby-sdk

Ruby

openapi-generator generate \
  -i https://rhumby.com/openapi.json \
  -g ruby \
  -o ./rhumby-sdk

API Testing Tools

Import the spec into your favorite API testing tool:

Postman: Import > Link > https://rhumby.com/openapi.json
Insomnia: Import > From URL > https://rhumby.com/openapi.json
Swagger UI: Point to https://rhumby.com/openapi.json
Bruno: Import > OpenAPI > https://rhumby.com/openapi.json

Validation

Use the spec to validate your requests and responses:

import Ajv from 'ajv';
import spec from './openapi.json';

const ajv = new Ajv();
const validate = ajv.compile(spec.components.schemas.Event);

if (!validate(eventData)) {
  console.error('Invalid event:', validate.errors);
}

Documentation Generation

Generate interactive documentation:

# Redoc
npx @redocly/cli build-docs openapi.json -o docs.html

# Swagger UI
docker run -p 8080:8080 -e SWAGGER_JSON=/openapi.json \
  -v $(pwd)/public:/usr/share/nginx/html \
  swaggerapi/swagger-ui

Mock Server

Create a mock API server for testing:

# Prism
npx @stoplight/prism-cli mock openapi.json

# MSW (Mock Service Worker)
npx msw init public/ --save

Example Usage

Once you've generated a client:

import { Configuration, EventsApi } from './rhumby-sdk';

const config = new Configuration({
  basePath: 'https://api.rhumby.com',
  headers: {
    Authorization: 'Bearer rhb_your_api_key_here'
  }
});

const api = new EventsApi(config);

// List upcoming events
const events = await api.listEvents({
  status: 'published',
  after: '2026-03-01',
  limit: 10
});

// Get event details with fleets
const event = await api.getEvent({
  slug: 'spring-series-2026',
  include: 'fleets,races'
});

// Register for an event
const registration = await api.registerForEvent({
  slug: 'spring-series-2026',
  registrationRequest: {
    fleetId: 'fleet-uuid',
    boatId: 'my-boat-uuid',
    crew: ['Alice', 'Bob']
  }
});

Staying in Sync

The OpenAPI spec is automatically updated when API routes change. To ensure you're always using the latest:

Subscribe to Rhumby API changelog at https://rhumby.com/changelog
Watch the GitHub repository for releases
Set up CI to regenerate your SDK on new spec versions

Contributing

Found an error in the spec? Report it at https://github.com/rhumby/api-issues

OpenAPI Specification

Spec URL

Download

What's Included

SDK Generation

TypeScript

Python

Go

Ruby

API Testing Tools

Validation

Documentation Generation

Mock Server

Example Usage

Staying in Sync

Contributing

On this page

OpenAPI Specification

Spec URL

Download

What's Included

SDK Generation

TypeScript

Python

Go

Ruby

API Testing Tools

Validation

Documentation Generation

Mock Server

Example Usage

Staying in Sync

Contributing

On this page