{"openapi":"3.1.0","info":{"title":"HealthSource Agent Body Context API","version":"1.0.0","description":"Read-only, user-authorized recovery and body context for approved HealthSource integrations. HealthSource is limited to wellness, recovery, fitness, performance reflection, and training readiness. Oura-derived data must not be used for diagnosis, advertising, resale, model training, fine-tuning, benchmarking, or unapproved redistribution."},"servers":[{"url":"https://healthsource.app"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/connection/status":{"get":{"operationId":"healthsource_get_connection_status","summary":"Get the user's source connection status","description":"Returns whether the authenticated HealthSource user has connected Oura, and a short-lived connect URL when available.","tags":["Connection"],"responses":{"200":{"description":"Connection status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConnectionStatus"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/recovery/today":{"get":{"operationId":"healthsource_recovery_today","summary":"Get today's recovery assessment","description":"Returns green/yellow/red recovery status, HRV/RHR baseline context, sleep context, temperature flag, confidence, and a practical training action.","tags":["Body Context"],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}}],"responses":{"200":{"description":"Get today's recovery assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryAssessment"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"healthsource_recovery_today_post","summary":"Get today's recovery assessment","description":"POST equivalent of the recovery assessment endpoint for platforms that prefer JSON request bodies.","tags":["Body Context"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"days":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}}}}}},"responses":{"200":{"description":"Get today's recovery assessment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecoveryAssessment"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/body-context":{"get":{"operationId":"healthsource_get_body_context","summary":"Get source-cited body context","description":"Returns the HealthSource body-context object for non-medical agent planning, coaching, recovery, productivity, or Daily Brief use.","tags":["Body Context"],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}}],"responses":{"200":{"description":"Get source-cited body context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BodyContext"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"healthsource_get_body_context_post","summary":"Get source-cited body context","description":"POST equivalent of the body-context endpoint for platforms that prefer JSON request bodies.","tags":["Body Context"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"days":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}}}}}},"responses":{"200":{"description":"Get source-cited body context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BodyContext"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/analysis-packet":{"get":{"operationId":"healthsource_get_analysis_packet","summary":"Get a model-ready Oura analysis packet","description":"Returns a compact model-ready Oura signal packet plus optional analysis prompt. The default response omits raw debug endpoints.","tags":["Body Context"],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}},{"name":"include_prompt","in":"query","required":false,"schema":{"type":"boolean","default":true,"description":"Whether to include a model-ready prompt with the packet."}}],"responses":{"200":{"description":"Get a model-ready Oura analysis packet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisPacketResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"healthsource_get_analysis_packet_post","summary":"Get a model-ready Oura analysis packet","description":"POST equivalent of the analysis-packet endpoint for platforms that prefer JSON request bodies.","tags":["Body Context"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"days":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."},"include_prompt":{"type":"boolean","default":true,"description":"Whether to include a model-ready prompt with the packet."}}}}}},"responses":{"200":{"description":"Get a model-ready Oura analysis packet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AnalysisPacketResponse"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/daily-brief":{"get":{"operationId":"healthsource_get_daily_brief","summary":"Get the HealthSource Daily Brief","description":"Returns a concise morning-ready recovery and training-readiness brief that can be delivered by HealthSource even before an AI platform supports native scheduled tool calls.","tags":["Body Context"],"parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."}}],"responses":{"200":{"description":"Get the HealthSource Daily Brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyBrief"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"post":{"operationId":"healthsource_get_daily_brief_post","summary":"Get the HealthSource Daily Brief","description":"POST equivalent of the Daily Brief endpoint for platforms that prefer JSON request bodies. Set persist_memory=true only from approved owned Daily Brief workers that should save the derived body-context snapshot.","tags":["Body Context"],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"days":{"type":"integer","minimum":7,"maximum":120,"default":90,"description":"Lookback window in calendar days. HealthSource defaults to 90 days for 3/7/14/30/60/90 recovery windows."},"persist_memory":{"type":"boolean","default":false,"description":"When true on an authenticated Daily Brief POST, HealthSource stores an encrypted derived body-context snapshot for longitudinal memory. It does not store raw Oura provider payloads."}}}}}},"responses":{"200":{"description":"Get the HealthSource Daily Brief","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DailyBrief"}}}},"401":{"description":"Missing or invalid bearer token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Oura is not connected for this user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/v1/openapi.json":{"get":{"operationId":"healthsource_get_openapi_spec","summary":"Get the HealthSource OpenAPI spec","tags":["Discovery"],"security":[],"responses":{"200":{"description":"OpenAPI spec","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tool-schemas":{"get":{"operationId":"healthsource_get_tool_schemas","summary":"Get generated AI provider tool schemas","tags":["Discovery"],"security":[],"responses":{"200":{"description":"Provider tool schemas","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/tool-schemas/{provider}":{"get":{"operationId":"healthsource_get_provider_tool_schema","summary":"Get one provider's tool schema","tags":["Discovery"],"security":[],"parameters":[{"name":"provider","in":"path","required":true,"schema":{"type":"string","enum":["gemini","xai","grok","perplexity"]}}],"responses":{"200":{"description":"Provider tool schema","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Unknown provider","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"HealthSource OAuth access token"}},"schemas":{"ConnectionStatus":{"type":"object","additionalProperties":true,"properties":{"provider":{"type":"string","const":"oura"},"connected":{"type":"boolean"},"authType":{"type":"string"},"actionRequired":{"type":"string","enum":["connect_oura"]},"connectUrl":{"type":"string","format":"uri"},"connectUrlExpiresAt":{"type":"string","format":"date-time"}},"required":["provider","connected","authType"]},"RecoveryAssessment":{"type":"object","additionalProperties":true,"properties":{"generatedAt":{"type":"string","format":"date-time"},"lookbackDays":{"type":"integer"},"latestDataDate":{"type":"string"},"status":{"type":"string","enum":["green","yellow","red"]},"suggestedAction":{"type":"string","enum":["train hard","train moderate","lift but reduce volume","rest / walk only"]},"confidence":{"type":"string","enum":["high","medium","low"]},"safetyBoundary":{"type":"string"}},"required":["generatedAt","lookbackDays","status","confidence","suggestedAction","safetyBoundary"]},"BodyContext":{"type":"object","additionalProperties":true,"properties":{"schemaVersion":{"type":"string","const":"healthsource.body-context.v0"},"generatedAt":{"type":"string","format":"date-time"},"lookbackDays":{"type":"integer"},"sources":{"type":"array","items":{"type":"object","additionalProperties":true}},"coverage":{"type":"object","additionalProperties":true},"memoryContext":{"type":"object","additionalProperties":true,"description":"Optional compact longitudinal memory built from encrypted HealthSource-derived snapshots for this user. It summarizes prior recovery statuses/actions and explicitly does not contain raw Oura provider payloads.","properties":{"schemaVersion":{"type":"string","const":"healthsource.body-context-memory.v0"},"sourceProvider":{"type":"string","const":"oura"},"snapshotCount":{"type":"integer"},"latestSnapshotDate":{"type":"string"},"storesRawProviderPayloads":{"type":"boolean","const":false},"snapshots":{"type":"array","items":{"type":"object","additionalProperties":true}}}},"recoveryContext":{"type":"object","additionalProperties":true},"safetyBoundary":{"type":"object","additionalProperties":true}},"required":["schemaVersion","generatedAt","lookbackDays","sources","coverage","recoveryContext","safetyBoundary"]},"AnalysisPacketResponse":{"type":"object","additionalProperties":true,"properties":{"packet":{"type":"object","additionalProperties":true},"prompt":{"type":"string"},"instructions":{"type":"string"}},"required":["packet","instructions"]},"DailyBrief":{"type":"object","additionalProperties":true,"properties":{"schemaVersion":{"type":"string","const":"healthsource.daily-brief.v0"},"title":{"type":"string"},"status":{"type":"string","enum":["green","yellow","red"]},"suggestedAction":{"type":"string","enum":["train hard","train moderate","lift but reduce volume","rest / walk only"]},"sections":{"type":"array","items":{"type":"object","additionalProperties":true}},"safetyBoundary":{"type":"object","additionalProperties":true}},"required":["schemaVersion","title","status","suggestedAction","sections","safetyBoundary"]},"ErrorResponse":{"type":"object","additionalProperties":true,"properties":{"error":{"type":"string"},"message":{"type":"string"},"actionRequired":{"type":"string"},"connectUrl":{"type":"string","format":"uri"}},"required":["error"]}}}}