{ "openapi": "3.1.0", "info": { "title": "MYOPL Public API", "description": "Free, unauthenticated public lookups through MYOPL's existing MCP endpoint: published player ratings, pickleball browse choices, officially licensed 2026 USA Pickleball rulebook evidence, MYOPL Help Center and website information. No account, API key or OAuth token is required for these five read-only tools. Requests are rate limited. This contract describes JSON-RPC over HTTP POST, not separate REST GET routes. Private account data and actions are outside this public contract.", "version": "1.0.0", "termsOfService": "https://myopl.net/terms-and-conditions/", "contact": { "name": "MYOPL Support", "url": "https://myopl.net", "email": "support@myopl.net" } }, "servers": [ { "url": "https://api.myopl.net", "description": "MYOPL production API" } ], "security": [], "externalDocs": { "description": "English and Spanish public MCP integration guides", "url": "https://ai.myopl.net/integration.md" }, "paths": { "/mcp": { "post": { "summary": "Call MYOPL public MCP tools", "operationId": "callMyoplPublicMcp", "description": "Initialize, list the tools, then call a named tool with its arguments. Send Content-Type: application/json and Accept: application/json, text/event-stream. After initialization send MCP-Protocol-Version: 2025-11-25. The service is stateless, returns JSON, and does not require a session ID or offer a persistent SSE stream. Browser calls are subject to the API Origin policy; wildcard CORS on the specification document does not change that policy.", "security": [], "parameters": [ { "name": "MCP-Protocol-Version", "in": "header", "required": false, "description": "Send after initialization; unsupported values are rejected.", "schema": { "type": "string", "enum": [ "2025-11-25" ] } } ], "x-max-request-body-bytes": 16384, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpRequest" }, "examples": { "initialize": { "value": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2025-11-25", "capabilities": {}, "clientInfo": { "name": "myopl-public-api-client", "version": "1.0.0" } } } }, "listTools": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" } }, "browseChoices": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "prepare_pickleball_browse", "arguments": { "location": "Jupiter, FL", "language": "en" } } } }, "playerRating": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "get_public_player_rating", "arguments": { "username": "example_player" } } } }, "rules": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_pickleball_rules", "arguments": { "query": "non-volley zone", "language": "en" } } } }, "help": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_myopl_help", "arguments": { "query": "RSVP", "language": "en" } } } }, "websiteSpanish": { "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "search_myopl_website", "arguments": { "query": "valoración OPL", "language": "es" } } } }, "initialized": { "value": { "jsonrpc": "2.0", "method": "notifications/initialized" } } } } } }, "responses": { "200": { "description": "JSON-RPC result or protocol error. Tool failures also use HTTP 200, with result.isError=true; a missing public player returns found=false, not HTTP 404.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/McpResponse" } } } }, "202": { "description": "Notification accepted; no response body and no tool execution." }, "400": { "description": "Unsupported MCP-Protocol-Version header.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "403": { "description": "Browser Origin is not allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "405": { "description": "Only HTTP POST is supported; GET does not open an SSE stream.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "406": { "description": "The Accept header does not permit application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "413": { "description": "Request body exceeds 16,384 bytes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "415": { "description": "Content-Type must be application/json.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "503": { "description": "Public agent service is not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HttpError" } } } }, "429": { "description": "Rate limit exceeded. Wait before retrying.", "headers": { "Retry-After": { "description": "Seconds to wait, when supplied.", "schema": { "type": "string" } } } }, "default": { "description": "Unexpected infrastructure or HTTP error. Do not interpret it as a successful tool result." } } } } }, "components": { "schemas": { "prepare_pickleball_browseArguments": { "type": "object", "additionalProperties": false, "properties": { "location": { "type": "string", "minLength": 1, "maxLength": 120 }, "language": { "type": "string", "enum": [ "en", "es" ], "default": "en" }, "category": { "type": "string", "enum": [ "courts", "clubs", "sessions" ] } }, "required": [ "location" ], "description": "No category default is applied. Omitting category returns choice_required. The trimmed location must be a named city, state or country; unsupported punctuation is rejected." }, "search_pickleball_rulesArguments": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "language": { "type": "string", "enum": [ "en", "es" ], "default": "en" } }, "required": [ "query" ], "description": "The live tool advertises en and es. Use en: es currently produces an isError tool response because the evidence is English." }, "search_myopl_helpArguments": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "language": { "type": "string", "enum": [ "en", "es" ], "default": "en" } }, "required": [ "query" ] }, "search_myopl_websiteArguments": { "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 1, "maxLength": 1000 }, "language": { "type": "string", "enum": [ "en", "es" ], "default": "en" } }, "required": [ "query" ] }, "get_public_player_ratingArguments": { "type": "object", "additionalProperties": false, "properties": { "username": { "type": "string", "pattern": "^[A-Za-z0-9_.-]{1,64}$", "maxLength": 64 } }, "required": [ "username" ] }, "PlayerRating": { "oneOf": [ { "type": "object", "properties": { "found": { "const": false }, "spoken_reply": { "type": "string" } }, "required": [ "found", "spoken_reply" ], "additionalProperties": false }, { "type": "object", "properties": { "found": { "const": true }, "username": { "type": "string" }, "sport": { "const": "pickleball" }, "singles_opl": { "type": [ "string", "null" ], "description": "Published decimal string or null; do not estimate a missing rating." }, "doubles_opl": { "type": [ "string", "null" ] }, "guidance": { "type": "string" }, "spoken_reply": { "type": "string" } }, "required": [ "found", "username", "sport", "singles_opl", "doubles_opl", "guidance", "spoken_reply" ], "additionalProperties": false } ] }, "BrowseChoices": { "type": "object", "properties": { "version": { "const": 1 }, "location": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "es" ] }, "sport": { "const": "pickleball" }, "spoken_reply": { "type": "string" }, "choices": { "type": "array", "items": { "type": "object", "properties": { "id": { "enum": [ "courts", "clubs", "sessions" ] }, "label": { "type": "string" }, "browse_section": { "enum": [ "courts", "clubs", "opls" ] } }, "required": [ "id", "label", "browse_section" ], "additionalProperties": false }, "minItems": 3, "maxItems": 3 }, "status": { "enum": [ "choice_required", "browse_ready" ] }, "guidance": { "type": "string" }, "selection": { "type": "object", "properties": { "category": { "enum": [ "courts", "clubs", "sessions" ] }, "browse_section": { "enum": [ "courts", "clubs", "opls" ] }, "query": { "type": "string" }, "sport": { "const": "pickleball" } }, "required": [ "category", "browse_section", "query", "sport" ], "additionalProperties": false } }, "required": [ "version", "location", "language", "sport", "spoken_reply", "choices", "status", "guidance" ], "additionalProperties": false }, "RuleEvidence": { "type": "object", "properties": { "rule": { "type": "string" }, "title": { "type": "string" }, "text": { "type": "string", "maxLength": 4000 }, "truncated": { "type": "boolean" }, "authority": { "type": "string" } }, "required": [ "rule", "title", "text", "truncated", "authority" ], "additionalProperties": false }, "RulesSearch": { "type": "object", "properties": { "source": { "type": "string" }, "governing_body": { "type": "string" }, "edition": { "type": "string" }, "language": { "type": "string" }, "source_url": { "type": "string", "format": "uri" }, "myopl_url": { "type": "string", "format": "uri" }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/RuleEvidence" }, "maxItems": 5 }, "clarification": { "type": [ "string", "null" ] }, "guidance": { "type": "string" }, "answer": { "type": "string", "description": "Present when the server resolver is enabled. Preserve qualifications and requests for clarification." } }, "required": [ "source", "governing_body", "edition", "language", "source_url", "myopl_url", "evidence", "clarification", "guidance" ], "additionalProperties": false }, "DocumentSearch": { "type": "object", "properties": { "source": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" }, "title": { "type": "string" }, "language": { "type": "string", "enum": [ "en", "es" ] }, "excerpt": { "type": "string", "maxLength": 1800 }, "truncated": { "type": "boolean" } }, "required": [ "url", "title", "language", "excerpt", "truncated" ], "additionalProperties": false }, "maxItems": 5 }, "clarification": { "type": [ "string", "null" ] }, "guidance": { "type": "string" } }, "required": [ "source", "results", "clarification", "guidance" ], "additionalProperties": false }, "TextContent": { "type": "object", "properties": { "type": { "const": "text" }, "text": { "type": "string" } }, "required": [ "type", "text" ], "additionalProperties": false }, "BrowseChoicesResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextContent" }, "minItems": 1 }, "structuredContent": { "$ref": "#/components/schemas/BrowseChoices" }, "isError": { "const": false } }, "required": [ "content", "structuredContent", "isError" ], "additionalProperties": false }, "DocumentSearchResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextContent" }, "minItems": 1 }, "structuredContent": { "$ref": "#/components/schemas/DocumentSearch" }, "isError": { "const": false } }, "required": [ "content", "structuredContent", "isError" ], "additionalProperties": false }, "PlayerRatingResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextContent" }, "minItems": 1 }, "structuredContent": { "$ref": "#/components/schemas/PlayerRating" }, "isError": { "const": false } }, "required": [ "content", "structuredContent", "isError" ], "additionalProperties": false }, "RulesSearchResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextContent" }, "minItems": 1 }, "structuredContent": { "$ref": "#/components/schemas/RulesSearch" }, "isError": { "const": false } }, "required": [ "content", "structuredContent", "isError" ], "additionalProperties": false }, "ToolErrorResult": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/TextContent" }, "minItems": 1 }, "structuredContent": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false }, "isError": { "const": true } }, "required": [ "content", "structuredContent", "isError" ], "additionalProperties": false }, "InitializeResult": { "type": "object", "properties": { "protocolVersion": { "const": "2025-11-25" }, "capabilities": { "type": "object", "properties": { "tools": { "type": "object", "properties": { "listChanged": { "const": false } }, "required": [ "listChanged" ], "additionalProperties": false } }, "required": [ "tools" ], "additionalProperties": false }, "serverInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": false }, "instructions": { "type": "string" } }, "required": [ "protocolVersion", "capabilities", "serverInfo", "instructions" ], "additionalProperties": false }, "ToolDefinition": { "type": "object", "properties": { "name": { "enum": [ "prepare_pickleball_browse", "search_pickleball_rules", "search_myopl_help", "search_myopl_website", "get_public_player_rating" ] }, "description": { "type": "string" }, "inputSchema": { "type": "object", "additionalProperties": true }, "annotations": { "type": "object", "properties": { "readOnlyHint": { "const": true }, "destructiveHint": { "const": false }, "idempotentHint": { "const": true }, "openWorldHint": { "const": true } }, "required": [ "readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint" ], "additionalProperties": false } }, "required": [ "name", "description", "inputSchema", "annotations" ], "additionalProperties": false }, "ToolsListResult": { "type": "object", "properties": { "tools": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" } } }, "required": [ "tools" ], "additionalProperties": false }, "InitializeRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "initialize" }, "params": { "type": "object", "properties": { "protocolVersion": { "type": "string" }, "capabilities": { "type": "object" }, "clientInfo": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" } }, "required": [ "name", "version" ], "additionalProperties": true } }, "required": [ "protocolVersion", "capabilities", "clientInfo" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "PingRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "ping" }, "params": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method" ], "additionalProperties": false }, "ToolsListRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/list" }, "params": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method" ], "additionalProperties": false }, "prepare_pickleball_browseRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "properties": { "name": { "const": "prepare_pickleball_browse" }, "arguments": { "$ref": "#/components/schemas/prepare_pickleball_browseArguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "search_pickleball_rulesRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "properties": { "name": { "const": "search_pickleball_rules" }, "arguments": { "$ref": "#/components/schemas/search_pickleball_rulesArguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "search_myopl_helpRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "properties": { "name": { "const": "search_myopl_help" }, "arguments": { "$ref": "#/components/schemas/search_myopl_helpArguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "search_myopl_websiteRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "properties": { "name": { "const": "search_myopl_website" }, "arguments": { "$ref": "#/components/schemas/search_myopl_websiteArguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "get_public_player_ratingRequest": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "method": { "const": "tools/call" }, "params": { "type": "object", "properties": { "name": { "const": "get_public_player_rating" }, "arguments": { "$ref": "#/components/schemas/get_public_player_ratingArguments" } }, "required": [ "name", "arguments" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "method", "params" ], "additionalProperties": false }, "InitializedNotification": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "method": { "const": "notifications/initialized" }, "params": { "type": "object", "properties": {}, "required": [], "additionalProperties": false } }, "required": [ "jsonrpc", "method" ], "additionalProperties": false }, "McpRequest": { "oneOf": [ { "$ref": "#/components/schemas/InitializeRequest" }, { "$ref": "#/components/schemas/PingRequest" }, { "$ref": "#/components/schemas/ToolsListRequest" }, { "$ref": "#/components/schemas/prepare_pickleball_browseRequest" }, { "$ref": "#/components/schemas/search_pickleball_rulesRequest" }, { "$ref": "#/components/schemas/search_myopl_helpRequest" }, { "$ref": "#/components/schemas/search_myopl_websiteRequest" }, { "$ref": "#/components/schemas/get_public_player_ratingRequest" }, { "$ref": "#/components/schemas/InitializedNotification" } ] }, "JsonRpcSuccess": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer" ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/InitializeResult" }, { "$ref": "#/components/schemas/ToolsListResult" }, { "type": "object", "properties": {}, "required": [], "additionalProperties": false }, { "$ref": "#/components/schemas/BrowseChoicesResult" }, { "$ref": "#/components/schemas/DocumentSearchResult" }, { "$ref": "#/components/schemas/PlayerRatingResult" }, { "$ref": "#/components/schemas/RulesSearchResult" }, { "$ref": "#/components/schemas/ToolErrorResult" } ] } }, "required": [ "jsonrpc", "id", "result" ], "additionalProperties": false }, "JsonRpcError": { "type": "object", "properties": { "jsonrpc": { "const": "2.0" }, "id": { "type": [ "string", "integer", "null" ] }, "error": { "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false } }, "required": [ "jsonrpc", "id", "error" ], "additionalProperties": false }, "McpResponse": { "oneOf": [ { "$ref": "#/components/schemas/JsonRpcSuccess" }, { "$ref": "#/components/schemas/JsonRpcError" } ] }, "HttpError": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ], "additionalProperties": false } } }, "x-mcp-protocol-version": "2025-11-25", "x-mcp-compatibility-endpoints": [ "https://pickleball.myopl.net/api/v1/public/mcp" ], "x-mcp-tools": [ { "name": "prepare_pickleball_browse", "description": "Offer courts to play at, clubs to join, or open play sessions for a named city, state or country. Returns a spoken reply and structured choices for UI or voice agents; does not search live availability or join/book anything.", "inputSchema": { "$ref": "#/components/schemas/prepare_pickleball_browseArguments" }, "outputSchema": { "$ref": "#/components/schemas/BrowseChoices" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "search_pickleball_rules", "description": "Search the validated official 2026 USA Pickleball Rulebook, used by MYOPL under an official licensing agreement with USA Pickleball. Returns English evidence, edition and rule citations, plus a grounded answer when the private resolver is enabled. Preserve requests for clarification; excerpts alone do not establish a complete ruling. No package download.", "inputSchema": { "$ref": "#/components/schemas/search_pickleball_rulesArguments" }, "outputSchema": { "$ref": "#/components/schemas/RulesSearch" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "search_myopl_help", "description": "Find published MYOPL Help Center instructions with source URLs. No account or conversation access.", "inputSchema": { "$ref": "#/components/schemas/search_myopl_helpArguments" }, "outputSchema": { "$ref": "#/components/schemas/DocumentSearch" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "search_myopl_website", "description": "Find published MYOPL product and website information with source URLs. No account or conversation access.", "inputSchema": { "$ref": "#/components/schemas/search_myopl_websiteArguments" }, "outputSchema": { "$ref": "#/components/schemas/DocumentSearch" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } }, { "name": "get_public_player_rating", "description": "Look up an exact public username and published OPL ratings. No email, telephone, location, match history or private profile fields.", "inputSchema": { "$ref": "#/components/schemas/get_public_player_ratingArguments" }, "outputSchema": { "$ref": "#/components/schemas/PlayerRating" }, "annotations": { "readOnlyHint": true, "destructiveHint": false, "idempotentHint": true, "openWorldHint": true } } ] }