{"components":{"securitySchemes":{"oauth2":{"description":"Delegated access on a Evening Companion member's behalf. Authorization code + PKCE (S256); see /auth.md.","flows":{"authorizationCode":{"authorizationUrl":"https://eveningcompanion.com/oauth/authorize","refreshUrl":"https://eveningcompanion.com/oauth/token","scopes":{"contacts:read":"Read companions' direct contact methods on your behalf","directory:read":"Browse the public companion directory","profile":"Read your account name and email"},"tokenUrl":"https://eveningcompanion.com/oauth/token"}},"type":"oauth2"}}},"info":{"description":"Public, read-only endpoints of the Evening Companion companion directory. Non-explicit listings only; no personal, member or admin data is exposed. Contacting a companion is arranged off-platform via member-gated contact details.","title":"Evening Companion Public API","version":"1.0.0"},"openapi":"3.1.0","paths":{"/api/auth/me":{"get":{"operationId":"getMe","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"security":[{"oauth2":["profile"]}],"summary":"The authenticated member's own account record"}},"/api/companions":{"get":{"operationId":"listCompanions","parameters":[{"description":"free-text name/city search","in":"query","name":"search","required":false,"schema":{"type":"string"}},{"description":"filter by city","in":"query","name":"city","required":false,"schema":{"type":"string"}},{"description":"filter by spoken languages","in":"query","name":"languages","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"filter by tags","in":"query","name":"tags","required":false,"schema":{"items":{"type":"string"},"type":"array"}},{"description":"only those available now","in":"query","name":"availableNow","required":false,"schema":{"type":"boolean"}},{"description":"only ID-verified","in":"query","name":"verified","required":false,"schema":{"type":"boolean"}},{"description":"maximum hourly price","in":"query","name":"priceMax","required":false,"schema":{"type":"integer"}},{"description":"minimum age","in":"query","name":"ageMin","required":false,"schema":{"type":"integer"}},{"description":"maximum age","in":"query","name":"ageMax","required":false,"schema":{"type":"integer"}},{"description":"featured|rating|price_asc|price_desc|newest","in":"query","name":"sort","required":false,"schema":{"type":"string"}},{"description":"1-based page number","in":"query","name":"page","required":false,"schema":{"type":"integer"}},{"description":"page size (max 60)","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"List companions"}},"/api/companions/meta":{"get":{"operationId":"getCompanionsMeta","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Filter facets (cities, languages, tags, ranges)"}},"/api/companions/{idOrSlug}":{"get":{"operationId":"getCompanion","parameters":[{"in":"path","name":"idOrSlug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Get a companion by id or slug"}},"/api/companions/{idOrSlug}/contacts":{"get":{"operationId":"getCompanionContacts","parameters":[{"in":"path","name":"idOrSlug","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"security":[{"oauth2":["contacts:read"]}],"summary":"A companion's direct contact methods. Members only — a guest receives 401 with a WWW-Authenticate challenge naming the Protected Resource Metadata."}},"/api/companions/{id}/reviews":{"get":{"operationId":"listReviews","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"integer"}},{"description":"1-based page number","in":"query","name":"page","required":false,"schema":{"type":"integer"}},{"description":"page size","in":"query","name":"pageSize","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"List a companion's reviews"}},"/api/health":{"get":{"operationId":"getHealth","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Service health"}},"/api/mcp":{"get":{"operationId":"getMcpCard","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"MCP server card"},"post":{"operationId":"mcpRpc","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"security":[{},{"oauth2":["contacts:read"]}],"summary":"MCP JSON-RPC 2.0 endpoint. The directory tools are public; get_companion_contacts additionally requires the contacts:read scope."}},"/api/rates":{"get":{"operationId":"getRates","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Foreign-exchange rate table (base EUR) for price conversion"}},"/api/settings":{"get":{"operationId":"getSettings","responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Public runtime settings"}},"/oauth/register":{"post":{"operationId":"oauthRegister","requestBody":{"content":{"application/json":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Dynamic client registration (RFC 7591). Public clients only; no secret is issued."}},"/oauth/revoke":{"post":{"operationId":"oauthRevoke","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"description":"OK"}},"summary":"Revoke a refresh token (RFC 7009)"}},"/oauth/token":{"post":{"operationId":"oauthToken","requestBody":{"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}},"description":"OK"}},"summary":"Exchange an authorization code (with PKCE) or refresh an access token"}}},"servers":[{"url":"https://eveningcompanion.com"}]}