{ "openapi": "3.1.0", "info": { "title": "BucketMate API", "version": "1.0.0", "description": "Public API specification for BucketMate - Modern S3 client and file manager for macOS, iOS, and Web. Provides endpoints for application downloads, changelog history, release metadata, waitlist signup, and license validation.", "contact": { "name": "BucketMate Support", "email": "support@bucketmate.app", "url": "https://www.bucketmate.app/contact" }, "license": { "name": "Proprietary", "url": "https://www.bucketmate.app/tos" } }, "servers": [ { "url": "https://api.bucketmate.app", "description": "Production API Server" }, { "url": "https://www.bucketmate.app", "description": "BucketMate Web" } ], "paths": { "/health": { "get": { "operationId": "getHealthStatus", "summary": "Health check", "description": "Returns the health and operational status of the BucketMate API service.", "responses": { "200": { "description": "Service is operational", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/download-url": { "get": { "operationId": "getDownloadUrl", "summary": "Get latest macOS download link", "description": "Retrieves the direct download URL for the latest macOS release of BucketMate alongside the current version string.", "responses": { "200": { "description": "Download payload with current version and URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DownloadPayload" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/changelog": { "get": { "operationId": "getChangelogEntries", "summary": "List all changelogs", "description": "Returns a chronological list of all BucketMate releases with release notes, dates, and version identifiers.", "responses": { "200": { "description": "Array of changelog entries", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/changelog/versions": { "get": { "operationId": "getChangelogVersions", "summary": "List all release versions", "description": "Returns an array of available release version strings.", "responses": { "200": { "description": "List of version strings", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "string", "example": "1.6" } } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/changelog/{version}": { "get": { "operationId": "getChangelogByVersion", "summary": "Get specific changelog entry", "description": "Returns the release notes and metadata for a specific BucketMate version.", "parameters": [ { "name": "version", "in": "path", "required": true, "description": "The release version (e.g. 1.6)", "schema": { "type": "string", "example": "1.6" } } ], "responses": { "200": { "description": "Changelog entry details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChangelogEntry" } } } }, "404": { "description": "Version not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/sitemap-data": { "get": { "operationId": "getSitemapData", "summary": "Get sitemap metadata", "description": "Returns release metadata used for sitemap indexing.", "responses": { "200": { "description": "Sitemap release list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitemapDataResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/waitlist": { "post": { "operationId": "joinWaitlist", "summary": "Join product waitlist", "description": "Subscribes an email to the product waitlist.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistInput" } } } }, "responses": { "200": { "description": "Successfully subscribed or already subscribed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WaitlistResponse" } } } }, "400": { "description": "Invalid email address", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/license/macos/activate": { "post": { "operationId": "activateMacosLicense", "summary": "Activate macOS license", "description": "Activates a purchased license key for a macOS installation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseActivationInput" } } } }, "responses": { "200": { "description": "Activation successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseActivationResponse" } } } }, "400": { "description": "Invalid license request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Device limit reached", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "License key not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/license/macos/validate": { "post": { "operationId": "validateMacosLicense", "summary": "Validate macOS license", "description": "Validates an existing active license registration for a macOS device.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseValidationInput" } } } }, "responses": { "200": { "description": "License is valid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LicenseValidationResponse" } } } }, "400": { "description": "Invalid validation request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "License not found or inactive", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "components": { "schemas": { "HealthResponse": { "type": "object", "required": ["status", "timestamp"], "properties": { "status": { "type": "string", "example": "ok" }, "timestamp": { "type": "string", "format": "date-time", "example": "2026-08-27T12:00:00.000Z" } } }, "DownloadPayload": { "type": "object", "required": ["downloadUrl", "version"], "properties": { "downloadUrl": { "type": "string", "format": "uri", "example": "https://static.bucketmate.app/BucketMate-1.6.dmg" }, "version": { "type": "string", "example": "1.6" } } }, "ChangelogEntry": { "type": "object", "required": ["version", "content"], "properties": { "version": { "type": "string", "example": "1.6" }, "content": { "type": "string", "example": "Added multi-workspace organization and presigned share links" }, "date": { "type": "string", "example": "2026-08-20" }, "githubUrl": { "type": "string", "format": "uri", "example": "https://github.com/davidtranjs/bucketmate-releases/releases/tag/v1.6" } } }, "SitemapDataResponse": { "type": "object", "required": ["releases"], "properties": { "releases": { "type": "array", "items": { "$ref": "#/components/schemas/ChangelogEntry" } } } }, "WaitlistInput": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email", "example": "user@example.com" } } }, "WaitlistResponse": { "type": "object", "required": ["success", "message"], "properties": { "success": { "type": "boolean", "example": true }, "message": { "type": "string", "example": "Successfully added to waitlist" }, "alreadyExists": { "type": "boolean", "example": false } } }, "LicenseActivationInput": { "type": "object", "required": ["licenseKey", "deviceId"], "properties": { "licenseKey": { "type": "string", "example": "BUCKETMATE-LIFETIME-XXXX-XXXX" }, "deviceId": { "type": "string", "minLength": 8, "maxLength": 120, "example": "mac-device-uuid-12345" }, "deviceLabel": { "type": "string", "maxLength": 120, "example": "MacBook Pro M3 Max" } } }, "LicenseActivationResponse": { "type": "object", "required": ["activationId", "licenseKeyId", "licenseKey"], "properties": { "activationId": { "type": "string", "example": "act_123456" }, "licenseKeyId": { "type": "string", "example": "lic_123456" }, "licenseKey": { "type": "object", "required": ["id", "status", "key", "isActive"], "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "granted" }, "key": { "type": "string" }, "isActive": { "type": "boolean", "example": true }, "productName": { "type": "string", "example": "BucketMate macOS" } } } } }, "LicenseValidationInput": { "type": "object", "required": ["licenseKey", "deviceId", "activationId"], "properties": { "licenseKey": { "type": "string", "example": "BUCKETMATE-LIFETIME-XXXX-XXXX" }, "deviceId": { "type": "string", "example": "mac-device-uuid-12345" }, "activationId": { "type": "string", "example": "act_123456" } } }, "LicenseValidationResponse": { "type": "object", "required": ["licenseKey"], "properties": { "licenseKey": { "type": "object", "required": ["id", "status", "key", "isActive"], "properties": { "id": { "type": "string" }, "status": { "type": "string", "example": "granted" }, "key": { "type": "string" }, "isActive": { "type": "boolean", "example": true }, "productName": { "type": "string", "example": "BucketMate macOS" } } } } }, "ErrorResponse": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message"], "properties": { "code": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "The requested resource was not found." }, "resolution": { "type": "string", "example": "Verify the endpoint parameters or check /openapi.json for valid paths." } } } } } } } }