{ "openapi": "3.0.3", "info": { "title": "TrueIntent Dating Platform API", "description": "API specification for TrueIntent, a purpose-driven, intentional dating web platform. Provides endpoints for discovery, profile matching, real-time messaging, WebRTC signaling, AI-generated icebreakers, and user preferences.", "version": "1.0.0", "contact": { "name": "TrueIntent Support", "url": "https://trueintent-dating.com" } }, "servers": [ { "url": "/", "description": "Current Server" } ], "paths": { "/api/profiles": { "get": { "summary": "Fetch discovery profiles", "description": "Returns candidate user profiles matching filters such as intent, location, vibe, and verification status.", "parameters": [ { "name": "userId", "in": "query", "schema": { "type": "integer" } }, { "name": "intent", "in": "query", "schema": { "type": "string" } }, { "name": "vibe", "in": "query", "schema": { "type": "string" } }, { "name": "search", "in": "query", "schema": { "type": "string" } }, { "name": "onlyPremium", "in": "query", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "List of user profiles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/UserProfile" } } } } } } } }, "/api/swipe": { "post": { "summary": "Record a swipe action", "description": "Records like, reject, or super_like with an optional introductory note.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromUserId": { "type": "integer" }, "toUserId": { "type": "integer" }, "status": { "type": "string", "enum": ["like", "reject", "super_like"] }, "intro": { "type": "string" } }, "required": ["fromUserId", "toUserId", "status"] } } } }, "responses": { "200": { "description": "Swipe processed successfully", "content": { "application/json": { "schema": { "type": "object", "properties": { "matched": { "type": "boolean" }, "status": { "type": "string" } } } } } } } } }, "/api/matches": { "get": { "summary": "Get confirmed matches", "parameters": [ { "name": "userId", "in": "query", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "List of matches", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Match" } } } } } } } }, "/api/messages": { "post": { "summary": "Send a message", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "fromUserId": { "type": "integer" }, "toUserId": { "type": "integer" }, "content": { "type": "string" }, "type": { "type": "string" } }, "required": ["fromUserId", "toUserId", "content"] } } } }, "responses": { "200": { "description": "Message recorded" } } } }, "/api/generate-icebreaker": { "post": { "summary": "Stream an AI-generated icebreaker", "description": "Uses Gemini to stream personalized conversational openers based on target bio and profile context.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "targetName": { "type": "string" }, "targetBio": { "type": "string" }, "targetHobbies": { "type": "string" }, "targetInterests": { "type": "string" }, "vibe": { "type": "string" } } } } } }, "responses": { "200": { "description": "Server-Sent Events / Chunked text stream with generated icebreaker", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/llms.txt": { "get": { "summary": "Agent context file", "description": "Markdown guidance file designed for AI agents and LLM tools per llms.txt standard.", "responses": { "200": { "description": "LLM instructions and system overview", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/.well-known/dns-aid.json": { "get": { "summary": "DNS-AID JSON Manifest", "description": "JSON representation of published DNS for AI Discovery (DNS-AID) records with DNSSEC keys per draft-mozleywilliams-dnsop-dnsaid and RFC 9460.", "responses": { "200": { "description": "DNS-AID records and DNSSEC validation schema", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/dns-aid.zone": { "get": { "summary": "DNS-AID Zone File", "description": "RFC 1035 zone file syntax containing DNS-AID SVCB, HTTPS, and TXT records for agent discovery.", "responses": { "200": { "description": "DNS zone text", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/.well-known/dns-aid.signed.zone": { "get": { "summary": "DNS-AID DNSSEC-Signed Master Zone File", "description": "RFC 4034/4035 master zone file signed with Algorithm 13 (ECDSAP256SHA256) containing DNSKEY, RRSIG, and NSEC records.", "responses": { "200": { "description": "Signed DNS zone text", "content": { "text/plain": { "schema": { "type": "string" } } } } } } }, "/dns-query": { "get": { "summary": "DNS-over-HTTPS (DoH) DNSSEC Resolver", "description": "RFC 8484 DNS-over-HTTPS query endpoint returning authenticated DNSSEC data with AD=true flag.", "parameters": [ { "name": "name", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "default": "ANY" } } ], "responses": { "200": { "description": "DNS query response with AD flag and RRSIG/DNSKEY records", "content": { "application/dns-json": { "schema": { "type": "object" } } } } } } }, "/.well-known/api-catalog": { "get": { "summary": "API Catalog (RFC 9727 / RFC 9264)", "description": "Returns machine-readable application/linkset+json describing all available APIs, documentation (service-doc), specifications (service-desc), and health check endpoints (status).", "responses": { "200": { "description": "RFC 9727 Linkset JSON array", "content": { "application/linkset+json": { "schema": { "type": "object" } } } } } } }, "/api/health": { "get": { "summary": "Platform Health Status", "description": "Returns system health, database status, and uptime for agent monitoring.", "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/http-message-signatures-directory": { "get": { "summary": "Web Bot Auth JWKS Directory", "description": "RFC 9421 / Web Bot Auth directory publishing JSON Web Key Set (JWKS) and bot identity for verifying signed bot/agent requests.", "responses": { "200": { "description": "Web Bot Auth directory and JWKS keys", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/jwks.json": { "get": { "summary": "JSON Web Key Set (JWKS)", "description": "Standard JWKS endpoint containing ES256 and Ed25519 public keys for HTTP Message Signature verification.", "responses": { "200": { "description": "JWKS keys array", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/openid-configuration": { "get": { "summary": "OpenID Connect Discovery 1.0 Metadata", "description": "Returns standard OIDC discovery document including issuer, authorization_endpoint, token_endpoint, jwks_uri, and supported grant types.", "responses": { "200": { "description": "OpenID Connect configuration document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-authorization-server": { "get": { "summary": "OAuth 2.0 Authorization Server Metadata (RFC 8414)", "description": "Returns RFC 8414 OAuth 2.0 Authorization Server metadata for automated AI agent authentication discovery.", "responses": { "200": { "description": "OAuth 2.0 authorization server metadata document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "summary": "OAuth 2.0 Protected Resource Metadata (RFC 9700)", "description": "Returns OAuth 2.0 Protected Resource Metadata including resource identifier, authorization_servers list, scopes_supported, bearer_methods_supported, and jwks_uri.", "responses": { "200": { "description": "OAuth 2.0 Protected Resource metadata document", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/auth.md": { "get": { "summary": "Auth.md Agent Registration & Authentication Specification", "description": "Returns Auth.md markdown document with machine and human readable instructions for AI agent registration and authentication.", "responses": { "200": { "description": "Auth.md markdown specification", "content": { "text/markdown": { "schema": { "type": "string" } } } } } } }, "/api/oauth/register": { "post": { "summary": "OAuth 2.0 Dynamic Client Registration (RFC 7591)", "description": "Register autonomous agents and AI clients dynamically to obtain client_id and client_secret credentials.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "201": { "description": "Client registration response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/oauth/claims": { "get": { "summary": "OAuth 2.0 Claims Verification & Identity Types", "description": "Returns supported identity types, claim schemas, and credential validation rules for agent operations.", "responses": { "200": { "description": "Claims metadata", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/oauth/token": { "post": { "summary": "OAuth 2.0 / OIDC Token Endpoint", "description": "Issue bearer access tokens for client_credentials, authorization_code, or refresh_token flows.", "requestBody": { "content": { "application/json": { "schema": { "type": "object" } }, "application/x-www-form-urlencoded": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "Access token response", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/agent-skills/index.json": { "get": { "summary": "Agent Skills Discovery Index", "description": "Returns standard Agent Skills Discovery index (RFC v0.2.0) declaring skills, descriptions, SKILL.md URLs, and SHA256 integrity digests.", "responses": { "200": { "description": "Agent Skills Discovery Index JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/.well-known/mcp.json": { "get": { "summary": "Model Context Protocol (MCP) Server Card", "description": "Returns standard MCP Server Card metadata (SEP-1649) declaring tools, resources, prompts, and transport endpoints.", "responses": { "200": { "description": "MCP Server Card JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } } }, "/api/mcp": { "post": { "summary": "Model Context Protocol (MCP) JSON-RPC 2.0 Endpoint", "description": "Streamable HTTP JSON-RPC 2.0 handler for MCP tools (match_profiles, get_profile, generate_icebreaker, etc.), resources, and prompts.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } }, "responses": { "200": { "description": "MCP JSON-RPC 2.0 response", "content": { "application/json": { "schema": { "type": "object" } } } } } }, "get": { "summary": "MCP Server Card via /api/mcp", "description": "Returns the MCP Server Card for agents querying the endpoint directly.", "responses": { "200": { "description": "MCP Server Card JSON", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "components": { "schemas": { "UserProfile": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "age": { "type": "integer" }, "bio": { "type": "string" }, "intent": { "type": "string" }, "image": { "type": "string" }, "is_premium": { "type": "integer" }, "is_verified": { "type": "integer" }, "location": { "type": "string" }, "vibe": { "type": "string" } } }, "Match": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "image": { "type": "string" }, "last_message": { "type": "string" }, "unread_count": { "type": "integer" } } } }, "securitySchemes": { "OAuth2": { "type": "oauth2", "description": "OAuth 2.0 Authorization Server (RFC 8414) and Protected Resource Metadata (RFC 9700) available at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server", "flows": { "authorizationCode": { "authorizationUrl": "/oauth/authorize", "tokenUrl": "/oauth/token", "refreshUrl": "/oauth/token", "scopes": { "openid": "OpenID Connect identification", "profile": "Access user profile and dating intent data", "email": "Access verified contact email", "dating.read": "Query profiles and matching compatibility", "dating.write": "Manage user preferences and swipes", "agent.match": "Execute autonomous AI matchmaking analysis", "agent.chat": "Send and receive agent-coordinated messages" } }, "clientCredentials": { "tokenUrl": "/oauth/token", "scopes": { "dating.read": "Query profiles and matching compatibility", "dating.write": "Manage user preferences and swipes", "agent.match": "Execute autonomous AI matchmaking analysis", "agent.chat": "Send and receive agent-coordinated messages" } } } }, "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Bearer token authentication. Protected resource discovery metadata: /.well-known/oauth-protected-resource" }, "OpenIDConnect": { "type": "openIdConnect", "openIdConnectUrl": "/.well-known/openid-configuration", "description": "OpenID Connect 1.0 Discovery endpoint" } } } }