{ "openapi": "3.1.0", "info": { "title": "Rhumby API", "version": "1.0.0", "description": "Sailing regatta management platform API. Manage events, registrations, results, and standings for yacht clubs and race organizers.", "contact": { "name": "Rhumby Support", "url": "https://rhumby.com/support", "email": "support@rhumby.com" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "servers": [ { "url": "http://localhost:3000", "description": "Development server" }, { "url": "https://api.rhumby.com", "description": "Production server" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Health", "description": "System health and status" }, { "name": "Events", "description": "Regatta and event management" }, { "name": "Organizations", "description": "Yacht clubs and sailing organizations" }, { "name": "Series", "description": "Multi-event series and seasons" }, { "name": "Registration", "description": "Event registration and sign-up" }, { "name": "Results", "description": "Race results and standings" }, { "name": "Sailors", "description": "Sailor profiles and racing history" }, { "name": "API Keys", "description": "API key management" }, { "name": "Embed Tokens", "description": "Widget embed tokens for public displays" }, { "name": "Webhooks", "description": "Webhook subscriptions for event notifications" } ], "paths": { "/api/v1/health": { "get": { "tags": [ "Health" ], "summary": "Health check", "description": "Check API health status. No authentication required.", "operationId": "getHealth", "security": [], "responses": { "200": { "description": "API is healthy", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "version": { "type": "string", "example": "1" }, "timestamp": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/v1/events": { "get": { "tags": [ "Events" ], "summary": "List events", "description": "Search and list regattas with filtering options", "operationId": "listEvents", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "description": "Filter by event status", "schema": { "type": "string", "enum": [ "published", "ongoing", "completed" ] } }, { "name": "q", "in": "query", "description": "Text search across name, venue, and description", "schema": { "type": "string" } }, { "name": "after", "in": "query", "description": "Filter events starting after this date", "schema": { "type": "string", "format": "date" } }, { "name": "before", "in": "query", "description": "Filter events starting before this date", "schema": { "type": "string", "format": "date" } }, { "name": "org", "in": "query", "description": "Filter by organization slug", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Events list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EventSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/events/{slug}": { "get": { "tags": [ "Events" ], "summary": "Get event details", "description": "Retrieve full event details with optional related data", "operationId": "getEvent", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } }, { "name": "include", "in": "query", "description": "Comma-separated list of related data to include", "schema": { "type": "string", "example": "fleets,registrations,races,results,documents" } } ], "responses": { "200": { "description": "Event details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EventDetail" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "put": { "tags": [ "Events" ], "summary": "Update event", "description": "Update event details. Requires write scope and organization membership.", "operationId": "updateEvent", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventUpdate" } } } }, "responses": { "200": { "description": "Event updated", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Event" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/events/{slug}/register": { "post": { "tags": [ "Registration" ], "summary": "Register for event", "description": "Register yourself and a boat for an event. Requires register scope.", "operationId": "registerForEvent", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegistrationRequest" } } } }, "responses": { "201": { "description": "Registration successful", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Registration" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/events/{slug}/results": { "get": { "tags": [ "Results" ], "summary": "Get event results", "description": "Retrieve race-by-race results for an event", "operationId": "getEventResults", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } }, { "name": "fleet", "in": "query", "description": "Filter by fleet ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "race", "in": "query", "description": "Filter by race number", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Event results", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "event": { "type": "string" }, "races": { "type": "array", "items": { "$ref": "#/components/schemas/RaceResults" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/events/{slug}/standings": { "get": { "tags": [ "Results" ], "summary": "Get event standings", "description": "Retrieve cumulative standings across all races", "operationId": "getEventStandings", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Event standings", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "event": { "type": "string" }, "standings": { "type": "array", "items": { "$ref": "#/components/schemas/StandingEntry" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/events/{slug}/races/{raceId}/results": { "post": { "tags": [ "Results" ], "summary": "Submit race results", "description": "Submit or update results for a specific race. Requires results scope.", "operationId": "submitRaceResults", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Event slug identifier", "schema": { "type": "string" } }, { "name": "raceId", "in": "path", "required": true, "description": "Race UUID", "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResultsSubmission" } } } }, "responses": { "200": { "description": "Results submitted", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Result" } }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/organizations": { "get": { "tags": [ "Organizations" ], "summary": "List organizations", "description": "Search and list yacht clubs and sailing organizations", "operationId": "listOrganizations", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Text search by organization name", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organizations list", "content": { "application/json": { "schema": { "type": "object", "properties": { "organizations": { "type": "array", "items": { "$ref": "#/components/schemas/OrganizationSummary" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/organizations/{slug}": { "get": { "tags": [ "Organizations" ], "summary": "Get organization details", "description": "Retrieve organization details with upcoming and recent events", "operationId": "getOrganization", "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "Organization slug identifier", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Organization details", "content": { "application/json": { "schema": { "type": "object", "properties": { "organization": { "$ref": "#/components/schemas/Organization" }, "upcomingEvents": { "type": "array", "items": { "$ref": "#/components/schemas/EventSummary" } }, "recentEvents": { "type": "array", "items": { "$ref": "#/components/schemas/EventSummary" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/series": { "get": { "tags": [ "Series" ], "summary": "List series", "description": "List multi-event racing series", "operationId": "listSeries", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "year", "in": "query", "description": "Filter by year", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Series list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SeriesSummary" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } } }, "/api/v1/sailors/{id}/history": { "get": { "tags": [ "Sailors" ], "summary": "Get sailor racing history", "description": "Retrieve a sailor's complete racing history with stats", "operationId": "getSailorHistory", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Sailor user ID", "schema": { "type": "string", "format": "uuid" } }, { "name": "year", "in": "query", "description": "Filter by year", "schema": { "type": "integer" } }, { "name": "limit", "in": "query", "description": "Maximum number of results (1-100)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Sailor history", "content": { "application/json": { "schema": { "type": "object", "properties": { "sailor": { "$ref": "#/components/schemas/Sailor" }, "stats": { "$ref": "#/components/schemas/SailorStats" }, "history": { "type": "array", "items": { "$ref": "#/components/schemas/SailorHistoryEntry" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" }, "count": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/keys": { "get": { "tags": [ "API Keys" ], "summary": "List your API keys", "description": "List all API keys for authenticated user. Uses session auth, not API key.", "operationId": "listApiKeys", "security": [ { "sessionAuth": [] } ], "responses": { "200": { "description": "API keys list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "post": { "tags": [ "API Keys" ], "summary": "Create API key", "description": "Create a new API key. The raw key is only shown once. Uses session auth.", "operationId": "createApiKey", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } } }, "responses": { "201": { "description": "API key created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/ApiKey" }, { "type": "object", "properties": { "apiKey": { "type": "string", "description": "Raw API key - save this now, it won't be shown again", "example": "rhb_abc123xyz789..." } }, "required": [ "apiKey" ] } ] }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } }, "delete": { "tags": [ "API Keys" ], "summary": "Revoke API key", "description": "Revoke an API key. Uses session auth.", "operationId": "revokeApiKey", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "API key ID to revoke", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "API key revoked", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/embed-tokens": { "get": { "tags": [ "Embed Tokens" ], "summary": "List embed tokens", "description": "List embed tokens for an organization. Uses session auth.", "operationId": "listEmbedTokens", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "organizationId", "in": "query", "required": true, "description": "Organization ID", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Embed tokens list", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/EmbedToken" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "post": { "tags": [ "Embed Tokens" ], "summary": "Create embed token", "description": "Create a new embed token for widgets. Uses session auth.", "operationId": "createEmbedToken", "security": [ { "sessionAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateEmbedTokenRequest" } } } }, "responses": { "201": { "description": "Embed token created", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/EmbedToken" }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" } } }, "delete": { "tags": [ "Embed Tokens" ], "summary": "Deactivate embed token", "description": "Deactivate an embed token. Uses session auth.", "operationId": "deactivateEmbedToken", "security": [ { "sessionAuth": [] } ], "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Token ID to deactivate", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Embed token deactivated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } }, "/api/v1/webhooks": { "get": { "tags": [ "Webhooks" ], "summary": "List webhooks", "description": "List all webhooks for your organization. Requires admin scope.", "operationId": "listWebhooks", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "List of webhooks", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types this webhook subscribes to" }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - Admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Webhooks" ], "summary": "Create webhook", "description": "Create a new webhook subscription. Returns the signing secret once - save it immediately. Requires admin scope.", "operationId": "createWebhook", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "events" ], "properties": { "url": { "type": "string", "format": "uri", "description": "Webhook endpoint URL (must be HTTPS in production)" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Event types to subscribe to", "example": [ "registration.created", "results.updated" ] } } } } } }, "responses": { "201": { "description": "Webhook created successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "secret": { "type": "string", "description": "Webhook signing secret - shown only once" } } }, "message": { "type": "string", "example": "Webhook created. Save the secret — it will not be shown again." } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - Admin scope required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/webhooks/{id}": { "get": { "tags": [ "Webhooks" ], "summary": "Get webhook", "description": "Get webhook details. Secret is never returned. Requires admin scope.", "operationId": "getWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID" } ], "responses": { "200": { "description": "Webhook details", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "patch": { "tags": [ "Webhooks" ], "summary": "Update webhook", "description": "Update webhook configuration. Requires admin scope.", "operationId": "updateWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "New webhook URL" }, "events": { "type": "array", "items": { "type": "string" }, "minItems": 1, "description": "Updated event subscription list" }, "active": { "type": "boolean", "description": "Enable or disable the webhook" } } } } } }, "responses": { "200": { "description": "Webhook updated successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" }, "lastTriggeredAt": { "type": [ "string", "null" ], "format": "date-time" }, "failureCount": { "type": "integer" }, "createdAt": { "type": "string", "format": "date-time" } } }, "message": { "type": "string" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } }, "delete": { "tags": [ "Webhooks" ], "summary": "Delete webhook", "description": "Delete a webhook subscription. Requires admin scope.", "operationId": "deleteWebhook", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Webhook ID" } ], "responses": { "200": { "description": "Webhook deleted successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Webhook deleted successfully" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API Key", "description": "API key with 'rhb_' prefix. Get your key at https://rhumby.com/dashboard/api-keys" }, "sessionAuth": { "type": "apiKey", "in": "cookie", "name": "next-auth.session-token", "description": "NextAuth session cookie (for web app endpoints)" } }, "schemas": { "Pagination": { "type": "object", "properties": { "limit": { "type": "integer" }, "offset": { "type": "integer" }, "hasMore": { "type": "boolean" } }, "required": [ "limit", "offset", "hasMore" ] }, "Event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "registrationOpen": { "type": "string", "format": "date-time" }, "registrationClose": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "published", "ongoing", "completed", "cancelled" ] }, "entryFee": { "type": [ "string", "null" ] }, "currency": { "type": "string", "default": "USD" }, "maxParticipants": { "type": [ "integer", "null" ] }, "nor": { "type": [ "string", "null" ] }, "sailingInstructions": { "type": [ "string", "null" ] }, "settings": { "type": [ "object", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "slug", "startDate", "endDate", "status" ] }, "EventSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "venue": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "draft", "published", "ongoing", "completed", "cancelled" ] }, "entryFee": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "maxParticipants": { "type": [ "integer", "null" ] }, "settings": { "type": [ "object", "null" ] }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } }, "required": [ "id", "name", "slug", "startDate", "endDate", "status" ] }, "EventDetail": { "allOf": [ { "$ref": "#/components/schemas/Event" }, { "type": "object", "properties": { "organization": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "fleets": { "type": "array", "items": { "$ref": "#/components/schemas/Fleet" } }, "registrations": { "type": "array", "items": { "$ref": "#/components/schemas/RegistrationWithDetails" } }, "races": { "type": "array", "items": { "$ref": "#/components/schemas/Race" } }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ResultWithDetails" } }, "documents": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } } } } ] }, "EventUpdate": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string" }, "venue": { "type": "string" }, "address": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "registrationOpen": { "type": "string", "format": "date-time" }, "registrationClose": { "type": "string", "format": "date-time" }, "maxParticipants": { "type": "integer", "minimum": 1 }, "entryFee": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "draft", "published", "ongoing", "completed", "cancelled" ] }, "nor": { "type": [ "string", "null" ] }, "sailingInstructions": { "type": [ "string", "null" ] } } }, "Fleet": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "classId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "maxBoats": { "type": [ "integer", "null" ] }, "scoringSystem": { "type": "string", "enum": [ "low_point", "high_point", "pursuit" ], "default": "low_point" }, "dropRaces": { "type": "integer", "default": 0 } }, "required": [ "id", "eventId", "name" ] }, "Race": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "fleetId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "raceNumber": { "type": "integer" }, "scheduledStart": { "type": "string", "format": "date-time" }, "actualStart": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "scheduled", "postponed", "started", "finished", "abandoned" ], "default": "scheduled" }, "courseDescription": { "type": [ "string", "null" ] }, "windDirection": { "type": [ "integer", "null" ], "description": "Wind direction in degrees" }, "windSpeed": { "type": [ "number", "null" ], "description": "Wind speed in knots" }, "conditions": { "type": [ "string", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "eventId", "fleetId", "name", "raceNumber", "status" ] }, "Registration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "eventId": { "type": "string", "format": "uuid" }, "fleetId": { "type": "string", "format": "uuid" }, "userId": { "type": "string", "format": "uuid" }, "boatId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "registered", "waitlisted", "cancelled", "no_show" ] }, "registrationTime": { "type": "string", "format": "date-time" }, "paymentStatus": { "type": "string", "enum": [ "pending", "paid", "refunded" ] }, "crew": { "type": "array", "items": { "type": "string" } }, "emergencyContact": { "type": [ "string", "null" ] }, "specialRequirements": { "type": [ "string", "null" ] } }, "required": [ "id", "eventId", "fleetId", "userId", "boatId", "status", "registrationTime", "paymentStatus" ] }, "RegistrationWithDetails": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "registered", "waitlisted", "cancelled", "no_show" ] }, "fleetId": { "type": "string", "format": "uuid" }, "registrationTime": { "type": "string", "format": "date-time" }, "sailor": { "type": "object", "properties": { "name": { "type": [ "string", "null" ] } } }, "boat": { "type": "object", "properties": { "name": { "type": "string" }, "sailNumber": { "type": [ "string", "null" ] }, "model": { "type": [ "string", "null" ] } } } } }, "RegistrationRequest": { "type": "object", "properties": { "fleetId": { "type": "string", "format": "uuid" }, "boatId": { "type": "string", "format": "uuid" }, "crew": { "type": "array", "items": { "type": "string" } }, "emergencyContact": { "type": "string" }, "specialRequirements": { "type": "string" } }, "required": [ "fleetId", "boatId" ] }, "Result": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "raceId": { "type": "string", "format": "uuid" }, "registrationId": { "type": "string", "format": "uuid" }, "finishPosition": { "type": [ "integer", "null" ] }, "finishTime": { "type": "string", "format": "date-time" }, "elapsedTime": { "type": [ "integer", "null" ], "description": "Elapsed time in seconds" }, "correctedTime": { "type": [ "integer", "null" ], "description": "Corrected time in seconds" }, "points": { "type": [ "number", "null" ] }, "penalty": { "type": "string", "enum": [ "DSQ", "DNF", "DNS", "DNC", "OCS", "BFD", "UFD", "RET", "RDG", "DPI", "SCP", "DNE" ] }, "penaltyPoints": { "type": [ "number", "null" ] }, "notes": { "type": [ "string", "null" ] } }, "required": [ "id", "raceId", "registrationId" ] }, "ResultWithDetails": { "type": "object", "properties": { "raceId": { "type": "string", "format": "uuid" }, "finishPosition": { "type": [ "integer", "null" ] }, "elapsedTime": { "type": [ "integer", "null" ] }, "correctedTime": { "type": [ "integer", "null" ] }, "points": { "type": [ "number", "null" ] }, "penalty": { "type": [ "string", "null" ] }, "sailor": { "type": [ "string", "null" ] }, "boatName": { "type": [ "string", "null" ] }, "sailNumber": { "type": [ "string", "null" ] } } }, "RaceResults": { "type": "object", "properties": { "raceNumber": { "type": "integer" }, "name": { "type": "string" }, "status": { "type": "string", "enum": [ "scheduled", "postponed", "started", "finished", "abandoned" ] }, "scheduledStart": { "type": "string", "format": "date-time" }, "actualStart": { "type": "string", "format": "date-time" }, "windDirection": { "type": [ "integer", "null" ] }, "windSpeed": { "type": [ "number", "null" ] }, "conditions": { "type": [ "string", "null" ] }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/ResultWithDetails" } } }, "required": [ "raceNumber", "name", "status", "results" ] }, "ResultsSubmission": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "registrationId": { "type": "string", "format": "uuid" }, "finishPosition": { "type": "integer", "minimum": 1 }, "elapsedTime": { "type": "integer", "minimum": 1, "description": "Elapsed time in seconds" }, "correctedTime": { "type": "integer", "minimum": 1, "description": "Corrected time in seconds" }, "penalty": { "type": "string", "enum": [ "DSQ", "DNF", "DNS", "DNC", "OCS", "BFD", "UFD", "RET", "RDG", "DPI", "SCP", "DNE" ] }, "notes": { "type": "string" } }, "required": [ "registrationId" ] }, "minItems": 1 } }, "required": [ "results" ] }, "StandingEntry": { "type": "object", "properties": { "position": { "type": "integer" }, "sailor": { "type": [ "string", "null" ] }, "boatName": { "type": [ "string", "null" ] }, "sailNumber": { "type": [ "string", "null" ] }, "totalPoints": { "type": "number" }, "raceCount": { "type": "integer" }, "bestFinish": { "type": [ "integer", "null" ] }, "avgFinish": { "type": "number" } }, "required": [ "position", "totalPoints", "raceCount", "avgFinish" ] }, "Document": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "nor", "si", "amendment", "results", "other" ] }, "name": { "type": "string" }, "url": { "type": "string" }, "uploadedAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "type", "name", "url" ] }, "Organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "usSailingNumber": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "pending", "active", "suspended" ] }, "createdAt": { "type": "string", "format": "date-time" }, "memberCount": { "type": "integer" } }, "required": [ "id", "name", "slug", "status" ] }, "OrganizationSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "memberCount": { "type": "integer" }, "eventCount": { "type": "integer" } }, "required": [ "id", "name", "slug", "memberCount", "eventCount" ] }, "SeriesSummary": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "season": { "type": [ "string", "null" ] }, "year": { "type": "integer" }, "status": { "type": "string", "enum": [ "draft", "active", "completed", "cancelled" ] }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } } }, "required": [ "id", "name", "slug", "year", "status" ] }, "Sailor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": [ "string", "null" ] }, "sailNumber": { "type": [ "string", "null" ] } }, "required": [ "id" ] }, "SailorStats": { "type": "object", "properties": { "totalEvents": { "type": "integer" }, "totalRaces": { "type": "integer" }, "avgPosition": { "type": [ "number", "null" ] }, "bestPosition": { "type": [ "integer", "null" ] }, "totalPoints": { "type": [ "number", "null" ] }, "wins": { "type": "integer" }, "podiums": { "type": "integer" } }, "required": [ "totalEvents", "totalRaces", "wins", "podiums" ] }, "SailorHistoryEntry": { "type": "object", "properties": { "registration": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "registrationTime": { "type": "string", "format": "date-time" } } }, "event": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "slug": { "type": "string" }, "startDate": { "type": "string", "format": "date-time" }, "endDate": { "type": "string", "format": "date-time" }, "venue": { "type": [ "string", "null" ] } } }, "organization": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" } } }, "boat": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "sailNumber": { "type": [ "string", "null" ] } } }, "boatClass": { "type": "object", "properties": { "name": { "type": "string" } } }, "stats": { "type": "object", "properties": { "totalRaces": { "type": "integer" }, "avgPosition": { "type": [ "number", "null" ] }, "bestPosition": { "type": [ "integer", "null" ] }, "totalPoints": { "type": [ "number", "null" ] }, "wins": { "type": "integer" }, "podiums": { "type": "integer" } } } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "keyPrefix": { "type": "string", "description": "First 12 characters for identification" }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "register", "results", "admin" ] } }, "rateLimit": { "type": "integer", "description": "Requests per hour" }, "lastUsedAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "keyPrefix", "scopes", "createdAt" ] }, "CreateApiKeyRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "read", "write", "register", "results", "admin" ] }, "default": [ "read" ] }, "expiresInDays": { "type": "integer", "minimum": 1, "maximum": 365 } }, "required": [ "name" ] }, "EmbedToken": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "token": { "type": "string" }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedEvents": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "views": { "type": "array", "items": { "type": "string", "enum": [ "standings", "results", "schedule", "register" ] } }, "theme": { "type": [ "object", "null" ] }, "active": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" } }, "required": [ "id", "name", "token", "views", "active", "createdAt" ] }, "CreateEmbedTokenRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 100 }, "organizationId": { "type": "string", "format": "uuid" }, "allowedOrigins": { "type": "array", "items": { "type": "string" } }, "allowedEvents": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "views": { "type": "array", "items": { "type": "string", "enum": [ "standings", "results", "schedule", "register" ] }, "minItems": 1 }, "theme": { "type": [ "object", "null" ] } }, "required": [ "name", "organizationId", "views" ] }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" } }, "required": [ "error" ] } }, "responses": { "Unauthorized": { "description": "Unauthorized - Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unauthorized", "message": "Invalid or missing API key. Get one at https://rhumby.com/dashboard/api-keys" } } } }, "Forbidden": { "description": "Forbidden - Insufficient permissions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Forbidden", "message": "You do not have permission to perform this action" } } } }, "NotFound": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Not found" } } } }, "BadRequest": { "description": "Bad Request - Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Validation error: Invalid input" } } } } } } }