OpenAPI Specification
Machine-readable API specification for code generation and tooling
The full Rhumby API is described by an OpenAPI 3.1 specification.
Spec URL
GET /api/v1/openapiReturns 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.tsPython
openapi-generator generate \
-i https://rhumby.com/openapi.json \
-g python \
-o ./rhumby-sdkGo
openapi-generator generate \
-i https://rhumby.com/openapi.json \
-g go \
-o ./rhumby-sdkRuby
openapi-generator generate \
-i https://rhumby.com/openapi.json \
-g ruby \
-o ./rhumby-sdkAPI 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-uiMock Server
Create a mock API server for testing:
# Prism
npx @stoplight/prism-cli mock openapi.json
# MSW (Mock Service Worker)
npx msw init public/ --saveExample 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