{ "openapi": "3.1.0", "info": { "title": "Healthspan / PlanScout Intake Insight API", "version": "1.2.0", "summary": "Completed-intake insight package for advisor-led conversations", "description": "Receives Oliver Lin's versioned PlanScout intake event, applies Healthspan's transparent six-dimension weighted model, and asynchronously returns a complete advisor insight package. The package includes readiness and AUM-exposure descriptors, evidence provenance, talking points, recommended Healthspan journeys, and reviewed LLM context. The outward contract never exposes the private numeric calculation.", "contact": { "name": "Black Flag Design", "url": "https://blackflag.design" } }, "servers": [ { "url": "https://blessed-squirrel-650.convex.site", "description": "Active integration deployment" } ], "tags": [ { "name": "Authentication", "description": "Clerk-backed PlanScout machine credentials" }, { "name": "Intake handshake", "description": "At-least-once intake receipt and qualitative result status" }, { "name": "Operations", "description": "Deployment and model readiness" } ], "paths": { "/oauth/token": { "post": { "tags": [ "Authentication" ], "operationId": "issuePlanScoutAccessToken", "summary": "Exchange PlanScout machine credentials for a Clerk M2M token", "description": "OAuth 2.0 client-credentials request shape backed by Clerk M2M. Cache the opaque bearer token until expiry and refresh after expiry or a 401.", "security": [], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "grant_type" ], "properties": { "grant_type": { "type": "string", "const": "client_credentials" }, "scope": { "type": "string", "const": "healthspan.intakes.write" }, "client_id": { "type": "string", "description": "Optional with HTTP Basic authentication." }, "client_secret": { "type": "string", "format": "password", "description": "Optional with HTTP Basic authentication." } } } } } }, "responses": { "200": { "description": "One-hour Clerk M2M access token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthTokenResponse" } } } }, "400": { "$ref": "#/components/responses/OAuthError" }, "401": { "$ref": "#/components/responses/OAuthError" } } } }, "/v1/intakes": { "post": { "tags": [ "Intake handshake" ], "operationId": "submitPlanScoutIntake", "summary": "Accept a completed PlanScout intake", "description": "Returns 202 as soon as the intake is authenticated, validated, and deduplicated. Delivery is at least once; eventId is the idempotency key. The qualitative result is delivered through the callback and can also be read from the protected status resource.", "security": [ { "planScoutOAuth": [ "healthspan.intakes.write" ] }, { "planScoutHmac": [] } ], "parameters": [ { "$ref": "#/components/parameters/PlanScoutTimestamp" }, { "$ref": "#/components/parameters/PlanScoutSignature" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlanScoutIntake" }, "examples": { "complete": { "summary": "Oliver's proposed intake shape", "value": { "eventType": "intake.submitted", "eventId": "f1c2e0a4-9b6d-4f2a-8e21-2c7b9a0d4e55", "eventTimestamp": "2026-07-10T16:30:00.000Z", "schemaVersion": "v1", "advisorId": "10482", "clientGuid": "b7e63d4a-1f88-4c0e-9a2f-3d51c6e9aa10", "planscoutPlanRequestId": "665f0a1b2c3d4e5f60718293", "advisor": { "name": "Jane Advisor", "company": "Summit Wealth Partners", "email": "jane@summitwealth.example" }, "client": { "hasPartner": true, "primary": { "firstName": "Robert", "lastName": "Miyazaki", "age": 64 }, "partner": { "firstName": "Susan", "lastName": "Miyazaki", "age": 61 } }, "intake": { "employment": { "primary": { "isRetired": false, "currentIncome": 145000, "expectedRetirementAge": 67 }, "partner": { "isRetired": false, "currentIncome": 60000, "expectedRetirementAge": 65 } }, "savings": { "totalAssets": 1170000 }, "goals": { "targetIncome": 164000, "legacyGoal": 250000 } }, "healthSupport": { "schemaVersion": "v1", "answers": [ { "key": "diet_frequency", "questionId": "HQ1", "type": "single_choice_scale", "subject": "primary", "selected": { "value": "often", "label": "Often", "ordinal": 3 } }, { "key": "community_connection", "questionId": "HQ2", "type": "single_choice_scale", "subject": "primary", "selected": { "value": "somewhat_connected", "label": "Somewhat connected", "ordinal": 2 } }, { "key": "health_conditions", "questionId": "HQ3", "type": "multi_select", "subject": "primary", "selected": [ { "value": "hypertension", "label": "Hypertension" } ], "noneSelected": false }, { "key": "care_reliance", "questionId": "HQ4", "type": "multi_select", "subject": "primary", "selected": [ { "value": "spouse_partner", "label": "Spouse / partner" }, { "value": "adult_child", "label": "Adult child" } ] }, { "key": "care_dependents", "questionId": "HQ5", "type": "multi_select", "subject": "primary", "selected": [ { "value": "parent", "label": "Parent" } ] }, { "key": "emergency_contact", "questionId": "HQ6", "type": "single_choice_with_name", "subject": "primary", "selected": { "value": "adult_child", "label": "Adult child" }, "contactName": "Emily Miyazaki" } ] }, "healthspan": { "state": "Colorado", "careAssessment": { "conditionSummary": "Hypertension managed with medication", "cognitionStage": "none", "adlGrid": { "bathing": "independent", "dressing": "independent", "toileting": "independent", "transferring": "independent", "continence": "independent", "feeding": "independent" }, "iadlGrid": { "medication_management": "cueing", "meal_prep": "independent", "housekeeping": "assist", "shopping": "independent", "transportation": "independent", "finances": "independent", "communication": "independent" }, "riskFlags": [], "dmeInUse": [], "caregiverHoursPerWeek": 20, "carePreferences": "Remain at home as long as practical", "state": "Colorado" } } } } } } } }, "responses": { "200": { "description": "Duplicate event already accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "202": { "description": "Accepted for asynchronous result delivery", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AcceptedResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } }, "/v1/intakes/{eventId}": { "get": { "tags": [ "Intake handshake" ], "operationId": "getIntakeStatus", "summary": "Read result and callback status", "security": [ { "planScoutOAuth": [ "healthspan.intakes.write" ] }, { "planScoutHmac": [] } ], "parameters": [ { "name": "eventId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Qualitative result and exact callback payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntakeStatus" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Event not found" } } } }, "/health": { "get": { "tags": [ "Operations" ], "operationId": "getHealth", "summary": "Check API and model readiness", "responses": { "200": { "description": "Healthy deployment", "content": { "application/json": { "schema": { "type": "object" } } } } } } } }, "webhooks": { "healthspanResult": { "post": { "operationId": "receiveHealthspanResult", "summary": "Receive the completed qualitative result", "description": "Healthspan posts this payload to PlanScout's configured QA or production callback. Callback delivery is at least once with a unique callback eventId and echoed advisorId, clientGuid, and planscoutPlanRequestId.", "parameters": [ { "name": "X-Healthspan-Timestamp", "in": "header", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "X-Healthspan-Signature", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CallbackPayload" } } } }, "responses": { "200": { "description": "Callback received and deduplicated" } } } } }, "components": { "securitySchemes": { "planScoutOAuth": { "type": "oauth2", "description": "Primary PlanScout-to-Healthspan machine authentication.", "flows": { "clientCredentials": { "tokenUrl": "https://blessed-squirrel-650.convex.site/oauth/token", "scopes": { "healthspan.intakes.write": "Submit intakes and read qualitative result status." } } } }, "planScoutHmac": { "type": "apiKey", "in": "header", "name": "X-PlanScout-Signature", "description": "Compatibility fallback: sha256= with a five-minute replay window." } }, "parameters": { "PlanScoutTimestamp": { "name": "X-PlanScout-Timestamp", "in": "header", "required": false, "schema": { "type": "integer", "format": "int64" }, "description": "Required only for HMAC authentication." }, "PlanScoutSignature": { "name": "X-PlanScout-Signature", "in": "header", "required": false, "schema": { "type": "string", "pattern": "^sha256=[0-9a-f]{64}$" }, "description": "Required only for HMAC authentication." } }, "responses": { "BadRequest": { "description": "Malformed JSON or request headers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, expired, or invalid machine authentication", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "OAuthError": { "description": "OAuth client authentication or token request failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthError" } } } }, "UnprocessableEntity": { "description": "Payload does not satisfy Oliver's intake v1 shape", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "OAuthTokenResponse": { "type": "object", "required": [ "access_token", "token_type", "expires_in", "scope" ], "properties": { "access_token": { "type": "string", "description": "Opaque Clerk M2M token." }, "token_type": { "type": "string", "const": "Bearer" }, "expires_in": { "type": "integer", "minimum": 1, "maximum": 3600 }, "scope": { "type": "string", "const": "healthspan.intakes.write" } } }, "OAuthError": { "type": "object", "required": [ "error", "error_description" ], "properties": { "error": { "type": "string" }, "error_description": { "type": "string" } } }, "PlanScoutIntake": { "type": "object", "required": [ "eventType", "eventId", "eventTimestamp", "schemaVersion", "advisorId", "clientGuid", "planscoutPlanRequestId", "advisor", "client", "intake", "healthSupport" ], "properties": { "eventType": { "const": "intake.submitted" }, "eventId": { "type": "string", "format": "uuid", "description": "Idempotency key for at-least-once delivery." }, "eventTimestamp": { "type": "string", "format": "date-time" }, "schemaVersion": { "const": "v1" }, "advisorId": { "type": "string" }, "clientGuid": { "type": "string", "format": "uuid" }, "planscoutPlanRequestId": { "type": "string" }, "advisor": { "type": "object", "additionalProperties": true }, "client": { "type": "object", "additionalProperties": true }, "intake": { "type": "object", "additionalProperties": true }, "estimatesApplied": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "Flags inputs estimated by PlanScout." }, "estimatedValues": { "type": "object", "additionalProperties": true }, "healthSupport": { "type": "object", "required": [ "schemaVersion", "answers" ], "properties": { "schemaVersion": { "const": "v1" }, "answers": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/HealthAnswer" } } } } }, "additionalProperties": true }, "HealthAnswer": { "type": "object", "required": [ "key", "questionId", "subject" ], "properties": { "key": { "type": "string" }, "questionId": { "type": "string", "examples": [ "HQ1" ] }, "label": { "type": "string" }, "type": { "type": "string" }, "subject": { "type": "string", "enum": [ "primary", "partner" ] }, "selected": {}, "noneSelected": { "type": "boolean" }, "otherText": { "type": [ "string", "null" ] }, "contactName": { "type": "string" } }, "additionalProperties": true }, "ReadinessResult": { "type": "object", "description": "Qualitative, advisor-support result. No private numeric calculation is exposed.", "required": [ "contractVersion", "modelVersion", "methodologyStatus", "presentation", "household", "people", "dataQuality", "advisorBrief", "conversationContext", "roadmap", "generatedAt" ], "properties": { "contractVersion": { "const": "v1.2" }, "modelVersion": { "const": "healthspan-insight-v1.0.0" }, "methodologyStatus": { "const": "operational_transparent_weighted_model" }, "presentation": { "type": "object", "required": [ "numericScoreExposed", "audience", "purpose" ], "properties": { "numericScoreExposed": { "const": false }, "audience": { "const": "licensed_financial_professional" }, "purpose": { "const": "advisor_conversation_support" } } }, "household": { "$ref": "#/components/schemas/ReadinessSummary" }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/PersonInsight" } }, "dataQuality": { "type": "object", "required": [ "answerCount", "estimatedInputKeys", "hasEstimatedInputs", "interpretation" ], "properties": { "answerCount": { "type": "integer" }, "estimatedInputKeys": { "type": "array", "items": { "type": "string" } }, "hasEstimatedInputs": { "type": "boolean" }, "interpretation": { "const": "initial_intake_subject_to_advisor_revision" } } }, "advisorBrief": { "type": "object", "required": [ "headline", "summary", "talkingPoints", "preparationGaps", "recommendedJourneys", "nextBestActions", "evidence", "detailsPath" ], "properties": { "headline": { "type": "string" }, "summary": { "type": "string" }, "talkingPoints": { "type": "array", "items": { "type": "string" } }, "preparationGaps": { "type": "array", "items": { "type": "string" } }, "recommendedJourneys": { "type": "array", "items": { "type": "string" } }, "nextBestActions": { "type": "array", "items": { "type": "string" } }, "evidence": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionEvidence" } }, "detailsPath": { "type": "string" } } }, "conversationContext": { "type": "object", "required": [ "schemaVersion", "purpose", "reviewRequired", "prohibitedUses", "promptInputs" ], "properties": { "schemaVersion": { "const": "v1" }, "purpose": { "const": "advisor_conversation_support" }, "reviewRequired": { "const": true }, "prohibitedUses": { "type": "array", "items": { "type": "string" } }, "promptInputs": { "type": "array", "items": { "type": "object", "required": [ "key", "value" ], "properties": { "key": { "type": "string" }, "value": { "type": "string" } } } } } }, "roadmap": { "type": "object", "required": [ "phase", "currentCapability", "fullPlanSynchronization", "methodologyAlignment" ], "properties": { "phase": { "const": "pilot_ready" }, "currentCapability": { "const": "completed_intake_to_advisor_insight" }, "fullPlanSynchronization": { "const": "planned_enhancement" }, "methodologyAlignment": { "const": "versioned_contract_ready" } } }, "generatedAt": { "type": "string", "format": "date-time" } } }, "ReadinessSummary": { "type": "object", "required": [ "status", "readiness", "indicator", "label", "aumExposure", "aggregation" ], "properties": { "status": { "type": "string", "enum": [ "classified", "insufficient_data" ] }, "readiness": { "type": [ "string", "null" ], "enum": [ "established", "building", "developing", "needs_support", null ] }, "indicator": { "type": "string", "enum": [ "green", "teal", "amber", "orange", "gray" ] }, "label": { "type": "string" }, "aumExposure": { "type": "string", "enum": [ "contained", "watch", "elevated", "priority", "unavailable" ] }, "aggregation": { "const": "person_average_with_shared_financial_runway" } } }, "PersonInsight": { "type": "object", "required": [ "subject", "status", "readiness", "indicator", "label", "answeredQuestions", "expectedQuestions", "completeness", "dimensions", "preparationGaps", "advisorTalkingPoints", "recommendedJourneys" ], "properties": { "subject": { "type": "string", "enum": [ "primary", "partner" ] }, "status": { "type": "string", "enum": [ "classified", "insufficient_data" ] }, "readiness": { "type": [ "string", "null" ], "enum": [ "established", "building", "developing", "needs_support", null ] }, "indicator": { "type": "string", "enum": [ "green", "teal", "amber", "orange", "gray" ] }, "label": { "type": "string" }, "answeredQuestions": { "type": "integer" }, "expectedQuestions": { "type": "integer" }, "completeness": { "type": "integer", "minimum": 0, "maximum": 100 }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/DimensionEvidence" } }, "preparationGaps": { "type": "array", "items": { "type": "string" } }, "advisorTalkingPoints": { "type": "array", "items": { "type": "string" } }, "recommendedJourneys": { "type": "array", "items": { "type": "string" } } } }, "DimensionEvidence": { "type": "object", "required": [ "key", "label", "descriptor", "source", "weight", "evidenceQuestionIds", "evidenceSummary", "journeyKey" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "descriptor": { "type": "string", "enum": [ "established", "building", "developing", "needs_support" ] }, "source": { "type": "string", "enum": [ "healthspan_question", "planscout_intake", "combined" ] }, "weight": { "type": "number", "minimum": 0, "maximum": 1 }, "evidenceQuestionIds": { "type": "array", "items": { "type": "string" } }, "evidenceSummary": { "type": "string" }, "journeyKey": { "type": "string" } } }, "AcceptedResponse": { "type": "object", "required": [ "accepted", "eventId", "duplicate", "status", "statusUrl", "resultContractVersion", "deliveryMode" ], "properties": { "accepted": { "const": true }, "eventId": { "type": "string", "format": "uuid" }, "duplicate": { "type": "boolean" }, "status": { "const": "accepted" }, "statusUrl": { "type": "string", "format": "uri" }, "resultContractVersion": { "const": "v1.2" }, "deliveryMode": { "const": "asynchronous_callback" }, "authentication": { "type": "string" } } }, "CallbackPayload": { "type": "object", "required": [ "eventType", "eventId", "sourceEventId", "eventTimestamp", "schemaVersion", "advisorId", "clientGuid", "planscoutPlanRequestId", "result" ], "properties": { "eventType": { "const": "healthspan.score.completed", "description": "Compatibility event name retained from Oliver's original callback proposal." }, "eventId": { "type": "string", "format": "uuid" }, "sourceEventId": { "type": "string", "format": "uuid" }, "eventTimestamp": { "type": "string", "format": "date-time" }, "schemaVersion": { "const": "v1.2" }, "advisorId": { "type": "string" }, "clientGuid": { "type": "string", "format": "uuid" }, "planscoutPlanRequestId": { "type": "string" }, "result": { "$ref": "#/components/schemas/ReadinessResult" } } }, "IntakeStatus": { "type": "object", "properties": { "eventId": { "type": "string", "format": "uuid" }, "scoreStatus": { "type": "string" }, "callbackStatus": { "type": "string" }, "result": { "$ref": "#/components/schemas/ReadinessResult" }, "callback": { "$ref": "#/components/schemas/CallbackPayload" } } }, "Error": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "details": { "type": "array", "items": { "type": "object" } } } } } } }