{"openapi":"3.1.0","info":{"title":"HIITplay Developer API","version":"1.0.0","description":"Public, machine-readable contracts for the anonymous curated workout preview, protected workout generation, OAuth discovery, and the HIITplay Streamable HTTP MCP endpoint.","contact":{"name":"HIITplay developer documentation","url":"https://hiitplay.fit/docs"}},"servers":[{"url":"https://hiitplay.fit","description":"HIITplay production"}],"externalDocs":{"description":"HIITplay developer documentation","url":"https://hiitplay.fit/docs"},"tags":[{"name":"Free workout","description":"Anonymous, deterministic workout preview for live testing."},{"name":"Workout generation","description":"Protected duration-based generation for active mobile or machine-payment capabilities."},{"name":"MCP","description":"Model Context Protocol transport for AI clients."},{"name":"Discovery","description":"OAuth and protected-resource metadata."}],"paths":{"/api/workouts/preview":{"get":{"operationId":"getFreeCuratedWorkoutPreview","summary":"Get the free curated HIIT workout","description":"Returns the permanent deterministic five-minute workout without authentication, an API key, payment, or side effects. This endpoint is the live HIITplay API sandbox.","tags":["Free workout"],"parameters":[{"name":"duration_minutes","in":"query","required":false,"description":"Requested curated duration. Omit to use the current five-minute default.","schema":{"type":"integer","minimum":1,"default":5,"enum":[5]}}],"responses":{"200":{"description":"The curated workout and browser playback URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FreeWorkoutPreview"}}}},"400":{"description":"The requested duration is malformed or has no curated workout.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/workouts":{"post":{"operationId":"createWorkoutWithCapability","summary":"Create a workout with an active capability","description":"Creates a generated workout for an authenticated mobile session or a supported machine-payment capability. Ordinary agent integrations should prefer the MCP workout.create tool.","tags":["Workout generation"],"security":[{"mobileBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkoutCreateRequest"}}}},"responses":{"200":{"description":"Generated workout data for the authenticated actor.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"description":"The JSON request or duration is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"The bearer credential is missing, invalid, or expired.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The actor does not have an active generation capability.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Workout generation rules cannot satisfy the duration.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"429":{"description":"The actor has exceeded the workout-generation rate limit.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"The deprecated x402 path is unavailable; the response points to MPP.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/mcp":{"post":{"servers":[{"url":"https://mcp.hiitplay.fit","description":"Canonical HIITplay MCP server"}],"operationId":"sendMcpRequest","summary":"Send a Streamable HTTP MCP request","description":"Sends a JSON-RPC 2.0 Model Context Protocol request. Initialize and discovery are anonymous; protected tools use OAuth 2.1 with the hiitplay.agent scope.","tags":["MCP"],"parameters":[{"name":"Mcp-Protocol-Version","in":"header","required":false,"description":"MCP protocol version negotiated by the client.","schema":{"type":"string","example":"2025-06-18"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"An MCP JSON or server-sent event response, depending on Accept.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"The JSON-RPC or MCP request is invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcErrorResponse"}}}},"401":{"description":"A supplied OAuth bearer token could not be verified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"The OAuth token lacks the hiitplay.agent scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"getOAuthProtectedResourceMetadata","summary":"Get OAuth protected-resource metadata","description":"Returns RFC 9728 discovery metadata for the HIITplay MCP resource.","tags":["Discovery"],"responses":{"200":{"description":"OAuth resource, authorization server, and scope metadata.","content":{"application/json":{"schema":{"type":"object","required":["resource","authorization_servers","scopes_supported"],"properties":{"resource":{"type":"string","format":"uri"},"authorization_servers":{"type":"array","items":{"type":"string","format":"uri"}},"scopes_supported":{"type":"array","items":{"type":"string"}}},"additionalProperties":true}}}}}}}},"components":{"securitySchemes":{"mobileBearer":{"type":"http","scheme":"bearer","bearerFormat":"opaque mobile session token","description":"A short-lived Mobile App Session access token. MCP clients use OAuth instead."},"mcpOAuth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://hiitplay.fit/oauth/agent/authorize","tokenUrl":"https://hiitplay.fit/api/auth/oauth2/token","refreshUrl":"https://hiitplay.fit/api/auth/oauth2/token","scopes":{"hiitplay.agent":"Use protected HIITplay workout, access, and billing tools."}}}}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","resolution"],"properties":{"code":{"type":"string","description":"Stable machine-readable code."},"message":{"type":"string","description":"Human-readable problem."},"resolution":{"type":"string","description":"Concrete recovery guidance for an agent or developer."},"details":{"type":"object","additionalProperties":true}},"additionalProperties":false}},"additionalProperties":false},"FreeWorkoutInterval":{"type":"object","required":["exercise","work_seconds"],"properties":{"exercise":{"type":"string"},"work_seconds":{"type":"integer","minimum":1},"rest_seconds":{"type":"integer","minimum":0}},"additionalProperties":false},"FreeWorkoutPhase":{"type":"object","required":["title","intervals"],"properties":{"title":{"type":"string"},"intervals":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/FreeWorkoutInterval"}}},"additionalProperties":false},"FreeWorkoutPreview":{"type":"object","required":["version","status","access","requested_duration_minutes","available_duration_minutes","workout_id","workout_name","duration_minutes","workout_url","phases","message"],"properties":{"version":{"type":"integer","const":1},"status":{"type":"string","const":"success"},"access":{"type":"string","const":"free_curated"},"requested_duration_minutes":{"type":"integer","enum":[5]},"available_duration_minutes":{"type":"array","items":{"type":"integer","enum":[5]}},"workout_id":{"type":"string"},"workout_name":{"type":"string"},"duration_minutes":{"type":"integer","enum":[5]},"workout_url":{"type":"string","format":"uri"},"phases":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/FreeWorkoutPhase"}},"message":{"type":"string"}},"additionalProperties":false},"WorkoutCreateRequest":{"type":"object","required":["workout_inputs"],"properties":{"workout_inputs":{"type":"object","required":["duration_minutes"],"properties":{"duration_minutes":{"type":"integer","minimum":1,"maximum":60,"description":"Requested generated-workout duration in minutes."}},"additionalProperties":false}},"additionalProperties":false},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string"},"params":{"type":"object","additionalProperties":true}},"additionalProperties":false},"JsonRpcResponse":{"type":"object","required":["jsonrpc"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"result":{"type":"object","additionalProperties":true},"error":{"$ref":"#/components/schemas/JsonRpcError"}},"additionalProperties":false},"JsonRpcError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{"type":"object","additionalProperties":true}},"additionalProperties":false},"JsonRpcErrorResponse":{"type":"object","required":["jsonrpc","error"],"properties":{"jsonrpc":{"type":"string","const":"2.0"},"id":{"oneOf":[{"type":"string"},{"type":"integer"},{"type":"null"}]},"error":{"$ref":"#/components/schemas/JsonRpcError"}},"additionalProperties":false}}}}