{ "openapi": "3.1.0", "info": { "title": "ForeverBetter API", "version": "0.1.0", "description": "ForeverBetter API and MCP-compatible service for genetics, biomarkers, wearables, lab locator handoffs, and dashboard specs." }, "servers": [ { "url": "https://fb-health-api.fly.dev" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/health": { "get": { "summary": "Health check", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/ready": { "get": { "summary": "Readiness check", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/version": { "get": { "summary": "Version metadata", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/endpoints": { "get": { "summary": "Endpoint catalog", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/.well-known/health-agent.json": { "get": { "summary": "Agent manifest", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/openapi.json": { "get": { "summary": "OpenAPI schema", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/auth/otp/start": { "post": { "summary": "Start Supabase OTP", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "should_create_user": { "type": "boolean" }, "email_redirect_to": { "type": "string" } } } } } } } }, "/auth/otp/verify": { "post": { "summary": "Verify Supabase OTP", "security": [], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email", "token" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "token": { "type": "string" }, "type": { "type": "string", "enum": [ "email", "signup", "recovery", "invite", "magiclink" ] } } } } } } } }, "/imports/file": { "post": { "summary": "Upload health data", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_id", "category" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "genetics", "biomarkers", "wearables", "behavioral" ] }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "provider": { "type": "string" }, "text": { "type": "string" }, "data_base64": { "type": "string" } }, "oneOf": [ { "required": [ "text" ] }, { "required": [ "data_base64" ] } ] } } } } } }, "/connections/{provider}/auth-url": { "post": { "summary": "Build provider OAuth URL", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "provider", "client_id", "redirect_uri" ], "properties": { "provider": { "type": "string", "enum": [ "whoop", "oura" ] }, "client_id": { "type": "string", "minLength": 1 }, "redirect_uri": { "type": "string", "minLength": 1 }, "state": { "type": "string" }, "scopes": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/connections/{provider}/token": { "post": { "summary": "Exchange provider OAuth code", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "code", "client_id", "client_secret", "redirect_uri" ], "additionalProperties": false, "properties": { "code": { "type": "string" }, "client_id": { "type": "string" }, "client_secret": { "type": "string" }, "redirect_uri": { "type": "string" } } } } } } } }, "/connections/wearables/sync": { "post": { "summary": "Sync wearable data", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "user_id" ], "additionalProperties": false, "properties": { "access_token": { "type": "string" }, "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "provider_user_id": { "type": "string" }, "external_user_id": { "type": "string" }, "api_base_url": { "type": "string" }, "types": { "type": "array", "items": { "type": "string" } }, "start": { "type": "string" }, "end": { "type": "string" }, "limit": { "type": "number", "minimum": 1, "maximum": 100 }, "async": { "type": "boolean" }, "scheduled_for": { "type": "string" } } } } } } } }, "/connections/wearables/jobs/{id}": { "get": { "summary": "Read queued wearable sync job status", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/analyses": { "post": { "summary": "Run health analysis", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_id", "source_ids" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "source_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "profile": { "type": "object", "additionalProperties": false, "properties": { "age": { "type": "number" }, "sex": { "type": "string", "enum": [ "male", "female" ] } } } } } } } } } }, "/analyses/{id}": { "get": { "summary": "Read analysis", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/genetics/jobs/{id}": { "get": { "summary": "Read queued genetic analysis job status", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/dashboard-specs/{analysis_id}": { "get": { "summary": "Read dashboard spec", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/query": { "post": { "summary": "Query health context", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "user_id", "query" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "analysis_ids": { "type": "array", "items": { "type": "string" } } } } } } } } }, "/labs/search": { "get": { "summary": "Find nearby labs", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } } } }, "/users/{user_id}/data/delete": { "post": { "summary": "Tombstone user data", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "organization_id": { "type": "string", "minLength": 1 } } } } } } } }, "/mcp": { "post": { "summary": "MCP JSON-RPC endpoint", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } }, "schemas": { "FileImportInput": { "type": "object", "additionalProperties": false, "required": [ "user_id", "category" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "category": { "type": "string", "enum": [ "genetics", "biomarkers", "wearables", "behavioral" ] }, "filename": { "type": "string" }, "content_type": { "type": "string" }, "provider": { "type": "string" }, "text": { "type": "string" }, "data_base64": { "type": "string" } }, "oneOf": [ { "required": [ "text" ] }, { "required": [ "data_base64" ] } ] }, "RunHealthAnalysisInput": { "type": "object", "additionalProperties": false, "required": [ "user_id", "source_ids" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "source_ids": { "type": "array", "minItems": 1, "items": { "type": "string" } }, "profile": { "type": "object", "additionalProperties": false, "properties": { "age": { "type": "number" }, "sex": { "type": "string", "enum": [ "male", "female" ] } } } } }, "QueryInput": { "type": "object", "additionalProperties": false, "required": [ "user_id", "query" ], "properties": { "user_id": { "type": "string", "minLength": 1 }, "organization_id": { "type": "string", "minLength": 1 }, "query": { "type": "string", "minLength": 1 }, "analysis_ids": { "type": "array", "items": { "type": "string" } } } }, "DashboardSpecInput": { "type": "object", "additionalProperties": false, "required": [ "analysis_id" ], "properties": { "analysis_id": { "type": "string", "minLength": 1 } } } } }, "x-endpoints": [ { "id": "imports.file", "method": "POST", "path": "/imports/file", "category": "imports", "scopes": [ "health:data:write" ], "mcpTool": "upload_health_data", "description": "Upload biomarker, wearable, genetic, or behavioral source data." }, { "id": "connections.auth_url", "method": "POST", "path": "/connections/:provider/auth-url", "category": "connections", "scopes": [ "health:connections:write" ], "mcpTool": "connect_health_source", "description": "Build an OAuth authorization URL for WHOOP or Oura." }, { "id": "connections.token", "method": "POST", "path": "/connections/:provider/token", "category": "connections", "scopes": [ "health:connections:write" ], "description": "Exchange a provider OAuth code for provider tokens." }, { "id": "connections.sync", "method": "POST", "path": "/connections/wearables/sync", "category": "connections", "scopes": [ "health:connections:write" ], "description": "Sync connected wearable observations through the configured wearable integration backend." }, { "id": "connections.jobs.read", "method": "GET", "path": "/connections/wearables/jobs/:id", "category": "connections", "scopes": [ "health:connections:write" ], "description": "Read queued wearable sync job status." }, { "id": "analyses.create", "method": "POST", "path": "/analyses", "category": "analyses", "scopes": [ "health:data:write" ], "mcpTool": "run_health_analysis", "description": "Run a health analysis from uploaded source IDs." }, { "id": "analyses.read", "method": "GET", "path": "/analyses/:id", "category": "analyses", "scopes": [ "health:data:read" ], "description": "Read a stored analysis result for the authenticated user." }, { "id": "genetics.jobs.read", "method": "GET", "path": "/genetics/jobs/:id", "category": "genetics", "scopes": [ "health:data:read" ], "description": "Read queued WGS/SNP-array analysis job status." }, { "id": "dashboard_specs.read", "method": "GET", "path": "/dashboard-specs/:analysis_id", "category": "dashboard_specs", "scopes": [ "health:data:read" ], "mcpTool": "get_dashboard_spec", "description": "Read a dashboard-ready JSON spec for an analysis." }, { "id": "query.create", "method": "POST", "path": "/query", "category": "query", "scopes": [ "health:data:read" ], "mcpTool": "query_health_context", "description": "Query normalized observations and derived interpretations." }, { "id": "labs.search", "method": "GET", "path": "/labs/search", "category": "labs", "scopes": [ "health:labs:read" ], "mcpTool": "find_nearby_labs", "description": "Find Quest and SYNLAB locator handoffs near a user-selected area." }, { "id": "data.delete", "method": "POST", "path": "/users/:user_id/data/delete", "category": "data", "scopes": [ "health:data:write" ], "description": "Tombstone tenant-scoped user data for deletion/export workflows." } ] }