{"openapi":"3.1.0","info":{"title":"Riblanx Developer API","version":"1.0.0","description":"Public OAuth 2.1 and Streamable HTTP MCP contract for tenant-scoped marketing operations.","contact":{"url":"https://review.riblanx.com/support"},"license":{"name":"Riblanx API Terms","url":"https://review.riblanx.com/terms"}},"servers":[{"url":"https://review.riblanx.com","description":"Riblanx public API origin"}],"externalDocs":{"description":"Interactive developer documentation","url":"https://review.riblanx.com/docs"},"security":[{"bearerAuth":[]}],"paths":{"/api/oauth/register":{"post":{"operationId":"registerOAuthClient","security":[],"summary":"Register a public OAuth client","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationRequest"}}}},"responses":{"201":{"description":"Client registration","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientRegistrationResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/oauth/authorize":{"get":{"operationId":"authorize","security":[],"summary":"Authorize a client with OAuth 2.1 + PKCE","parameters":[{"$ref":"#/components/parameters/ClientId"},{"$ref":"#/components/parameters/RedirectUri"},{"$ref":"#/components/parameters/CodeChallenge"},{"$ref":"#/components/parameters/State"}],"responses":{"302":{"description":"Redirect to the registered callback with an authorization code"},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/oauth/token":{"post":{"operationId":"exchangeAuthorizationCode","security":[],"summary":"Exchange a code or refresh token","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/TokenRequest"}}}},"responses":{"200":{"description":"Bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/mcp":{"post":{"operationId":"mcpJsonRpc","summary":"Call MCP JSON-RPC methods","description":"Use initialize, tools/list, tools/call and resources/read over Streamable HTTP. The live tool catalog is discovered at runtime.","parameters":[{"$ref":"#/components/parameters/McpProtocolVersion"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcRequest"}}}},"responses":{"200":{"description":"JSON-RPC result or event stream","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JsonRpcResponse"}},"text/event-stream":{"schema":{"type":"string"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"OAuth 2.1 access token"}},"parameters":{"ClientId":{"name":"client_id","in":"query","required":true,"schema":{"type":"string"}},"RedirectUri":{"name":"redirect_uri","in":"query","required":true,"schema":{"type":"string","format":"uri"}},"CodeChallenge":{"name":"code_challenge","in":"query","required":true,"schema":{"type":"string"}},"State":{"name":"state","in":"query","required":true,"schema":{"type":"string"}},"McpProtocolVersion":{"name":"MCP-Protocol-Version","in":"header","required":false,"schema":{"type":"string","example":"2025-06-18"}}},"schemas":{"ClientRegistrationRequest":{"type":"object","required":["client_name","redirect_uris"],"properties":{"client_name":{"type":"string","minLength":1},"redirect_uris":{"type":"array","minItems":1,"items":{"type":"string","format":"uri"}}}},"ClientRegistrationResponse":{"type":"object","required":["client_id"],"properties":{"client_id":{"type":"string"},"client_name":{"type":"string"},"redirect_uris":{"type":"array","items":{"type":"string","format":"uri"}},"token_endpoint_auth_method":{"type":"string","example":"none"}}},"TokenRequest":{"type":"object","required":["grant_type","client_id"],"properties":{"grant_type":{"type":"string","enum":["authorization_code","refresh_token"]},"client_id":{"type":"string"},"code":{"type":"string"},"code_verifier":{"type":"string"},"redirect_uri":{"type":"string","format":"uri"},"refresh_token":{"type":"string"},"resource":{"type":"string","format":"uri","example":"https://review.riblanx.com/mcp"}}},"TokenResponse":{"type":"object","required":["access_token","token_type","expires_in"],"properties":{"access_token":{"type":"string","description":"Never log or expose this value."},"token_type":{"type":"string","example":"Bearer"},"expires_in":{"type":"integer"},"refresh_token":{"type":"string"},"scope":{"type":"string"}}},"JsonRpcRequest":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"}]},"method":{"type":"string","enum":["initialize","tools/list","tools/call","resources/read"]},"params":{"type":"object","additionalProperties":true}}},"JsonRpcResponse":{"type":"object","properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{},"result":{"type":"object","additionalProperties":true},"error":{"type":"object","additionalProperties":true}}},"Problem":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}},"Forbidden":{"description":"Scope, tenant or asset not authorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"x-riblanx":{"resource":"https://review.riblanx.com/mcp","discovery":"https://review.riblanx.com/.well-known/oauth-protected-resource/mcp","toolCatalog":"Call tools/list at runtime; tool schemas are authoritative."}}