{ "openapi": "3.1.0", "info": { "title": "Kinellect API", "version": "1.0.0", "description": "The API your backend calls to use Kinellect coaching. Read the integration guide for concepts, onboarding and conventions. Every POST and PUT requires an Idempotency-Key header. Requests reject unknown fields. Work that involves a model or your connector returns 202 with an Operation to poll.\n\nGenerated from the Kinellect source at commit `16cf66585dcc`." }, "paths": { "/v1/subjects/{subject_ref}": { "delete": { "summary": "Delete or replay deletion of one Subject", "description": "Requires the context:write scope. Deletion atomically tombstones the Subject, cancels its queued or running Operations and erases its coaching data, keeping only a minimal tombstone. Later polls of erased Operations return 404 and replays of earlier Subject requests return 409 subject_deleted.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Subject deleted, already deleted, or an identical transition replayed", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "A valid Idempotency-Key header is required" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing context:write scope" }, "404": { "description": "Unknown or cross-tenant Subject" }, "409": { "description": "Idempotency conflict" } }, "tags": [ "Subject lifecycle" ], "operationId": "deleteSubject" } }, "/v1/subjects/{subject_ref}/reactivate": { "post": { "summary": "Reactivate or replay reactivation of one deleted Subject", "description": "Requires the context:write scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Subject reactivated or an identical transition replayed", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "type": "null" } } } }, "400": { "description": "A valid Idempotency-Key header is required" }, "401": { "description": "Authentication required" }, "403": { "description": "Missing context:write scope" }, "404": { "description": "Unknown or cross-tenant Subject" }, "409": { "description": "Idempotency conflict" }, "422": { "description": "Subject is already active" } }, "tags": [ "Subject lifecycle" ], "operationId": "reactivateSubject" } }, "/v1/client-configurations/{configuration_version}/activate": { "put": { "summary": "Activate or replay one immutable tenant coaching configuration version", "description": "Requires the configuration:write scope. The opaque connector registration must have been provisioned for this tenant by an operator; endpoint and credential ownership cannot be created or changed through this API.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "configuration_version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateClientConfiguration" } } } }, "responses": { "200": { "description": "Existing identical version replayed. An exact replay does not call the connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientConfigurationActivation" } } } }, "201": { "description": "Configuration activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClientConfigurationActivation" } } } }, "400": { "description": "A valid Idempotency-Key header is required, or the request body is not valid JSON." }, "401": { "description": "Missing or invalid API token", "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "const": "about:blank" }, "title": { "const": "Unauthorized" }, "status": { "const": 401 }, "detail": { "const": "A valid API token is required." } } } } } }, "403": { "description": "Missing configuration:write scope" }, "409": { "description": "Idempotency key reused with different content, the same version already stored with different content, or a version that is not newer than the active version" }, "422": { "description": "Invalid or unknown request field, incomplete capability bundle or mismatched policy, duplicate policy capability, unavailable connector registration, connector contract version other than the registered version, or an enabled connector capability that the connector does not advertise" }, "503": { "description": "Connector capability discovery failed (unreachable, non-2xx, invalid response, or not completed within 10 seconds), or API-token authentication is temporarily unavailable" } }, "tags": [ "Configuration" ], "operationId": "activateClientConfiguration" } }, "/v1/subjects/{subject_ref}/context/{context_version}": { "put": { "summary": "Store or replay one immutable authoritative subject-context version", "description": "Requires the context:write scope. A snapshot is current exactly while effective_at <= now < valid_through.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "context_version", "in": "path", "required": true, "schema": { "type": "integer", "minimum": 1 } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PutSubjectContext" } } } }, "responses": { "200": { "description": "Existing identical context replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectContextWrite" } } } }, "201": { "description": "Context stored", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectContextWrite" } } } }, "403": { "description": "Missing context:write scope" }, "404": { "description": "Unknown or cross-tenant Subject" }, "409": { "description": "Idempotency, version, monotonicity, or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid or unknown request field" } }, "tags": [ "Subject context" ], "operationId": "putSubjectContext" } }, "/v1/threads": { "post": { "summary": "Create or replay a tenant-scoped Conversation Thread", "description": "Requires the conversation:write scope.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "external_subject_ref" ], "properties": { "external_subject_ref": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[^\\u0000]*$", "description": "Limited to 200 UTF-8 bytes; NUL bytes are not allowed.", "x-max-utf8-bytes": 200 }, "main": { "type": "boolean", "default": false } } } } } }, "responses": { "201": { "description": "Thread created or replayed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationThread" } } } }, "409": { "description": "Idempotency or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid request" } }, "tags": [ "Conversation" ], "operationId": "createThread" } }, "/v1/threads/{thread_ref}/turns": { "post": { "summary": "Accept one immutable user Turn", "description": "Requires the conversation:write scope. Processing continues durably after the request returns.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "thread_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "message" ], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 16000, "pattern": "^[^\\u0000]*$", "description": "Limited to 16000 UTF-8 bytes; NUL bytes are not allowed.", "x-max-utf8-bytes": 16000 } } } } } }, "responses": { "202": { "description": "Durable Operation accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOperation" } } } }, "404": { "description": "Thread not found" }, "409": { "description": "Idempotency, active-Operation, or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid request" }, "429": { "$ref": "#/components/responses/OperationAdmissionRejected" } }, "tags": [ "Conversation" ], "operationId": "createTurn" } }, "/v1/operations/{operation_ref}": { "get": { "summary": "Poll a Conversation Operation", "description": "Requires the conversation:read scope. Unknown and cross-tenant references are indistinguishable.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "operation_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One of queued, running, completed, failed, cancelled, or expired", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversationOperation" } } } }, "404": { "description": "Unknown or cross-tenant Operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/NotFoundProblem" } } } } }, "tags": [ "Conversation" ], "operationId": "getConversationOperation" } }, "/v1/workout-drafts": { "post": { "summary": "Request or replay one validated workout draft", "description": "Requires the workout:write scope. The server pins the execution mode when the durable Operation is accepted; callers cannot select a provider, model, prompt, or execution mode.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestWorkoutDraft" } } } }, "responses": { "202": { "description": "Durable workout-generation Operation accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutGenerationOperation" } } } }, "403": { "description": "Missing workout:write scope" }, "404": { "description": "Unknown or cross-tenant Subject" }, "409": { "description": "Idempotency, active-Operation, or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid or unknown request field" }, "429": { "$ref": "#/components/responses/OperationAdmissionRejected" } }, "tags": [ "Workout drafts" ], "operationId": "requestWorkoutDraft" } }, "/v1/subjects/{subject_ref}/workout-draft-operations/{operation_ref}": { "get": { "summary": "Poll a subject-scoped workout-generation Operation", "description": "Requires the workout:read scope. Unknown and cross-tenant Subject and Operation references are indistinguishable.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One of queued, running, completed, failed, cancelled, or expired", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutGenerationOperation" } } } }, "403": { "description": "Missing workout:read scope" }, "404": { "description": "Unknown or cross-tenant Subject or Operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/NotFoundProblem" } } } } }, "tags": [ "Workout drafts" ], "operationId": "getWorkoutDraftOperation" } }, "/v1/daily-plans": { "post": { "summary": "Request or replay one daily coaching decision", "description": "Requires the coaching:write scope. The server pins real_ai only when the daily policy permits nested generation; otherwise the pin is null; callers cannot select a provider, model, prompt, or execution mode.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestDailyPlan" } } } }, "responses": { "202": { "description": "Durable daily-coaching Operation accepted", "headers": { "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlanOperation" } } } }, "403": { "description": "Missing coaching:write scope" }, "404": { "description": "Unknown or cross-tenant Subject" }, "409": { "description": "Idempotency, active-Operation, or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid or unknown request field" }, "429": { "$ref": "#/components/responses/OperationAdmissionRejected" } }, "tags": [ "Daily plans" ], "operationId": "requestDailyPlan" } }, "/v1/subjects/{subject_ref}/daily-plan-operations/{operation_ref}": { "get": { "summary": "Poll a subject-scoped daily-coaching Operation", "description": "Requires the coaching:read scope. Unknown and cross-tenant Subject and Operation references are indistinguishable.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "One of queued, running, completed, failed, cancelled, or expired", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DailyPlanOperation" } } } }, "403": { "description": "Missing coaching:read scope" }, "404": { "description": "Unknown or cross-tenant Subject or Operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/NotFoundProblem" } } } } }, "tags": [ "Daily plans" ], "operationId": "getDailyPlanOperation" } }, "/v1/workout-acceptances": { "post": { "summary": "Request or replay explicit workout acceptance", "description": "Requires workout:write, authenticated tenant identity and Idempotency-Key. Returns a durable Operation; a separate worker dispatches the immutable saved source. Save and atomic save_and_schedule require their independently activated capabilities. confirmation_required needs explicit_user_approval for the exact selection; auto_execute still requires this request. Professional-review, proposal-only and rejected policies deny execution. Admission and pre-marker first dispatch recheck source, context, configuration, capability, policy and date/zone using application time. After possible dispatch, bounded recovery retains the original command, registration, action identity and connector key. Same-key same-request replay returns the original Operation even if currentness changed; changed request conflicts. This endpoint does not generate content, infer approval, or move or cancel schedules.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RequestWorkoutAcceptance" } } } }, "responses": { "202": { "description": "Durable acceptance Operation accepted or replayed", "headers": { "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutAcceptanceOperation" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Missing workout:write scope" }, "404": { "description": "Unknown or cross-scope Subject or source" }, "409": { "description": "Idempotency or Subject tombstone conflict", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid or unknown request field or inadmissible selection" }, "429": { "$ref": "#/components/responses/OperationAdmissionRejected" }, "400": { "description": "A valid Idempotency-Key header is required." } }, "tags": [ "Workout acceptance" ], "operationId": "requestWorkoutAcceptance" } }, "/v1/subjects/{subject_ref}/workout-acceptance-operations/{operation_ref}": { "get": { "summary": "Poll a subject-scoped workout acceptance Operation", "description": "Requires workout:read. Unknown and cross-tenant or cross-Subject references are indistinguishable and retain native Symfony Problem Details with detail: Not Found. Completed means a validated matching connector business result: only confirmed contains receipt and workout references/versions, plus schedule references/versions for save_and_schedule. Conflict and rejected contain only their safe business code. Exhausted uncertain recovery is failed with connector_unconfirmed and no result; the action may have taken effect. Polling does not dispatch another action.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Subject-scoped acceptance Operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutAcceptanceOperation" } } } }, "401": { "description": "Authentication required" }, "403": { "description": "Missing workout:read scope" }, "404": { "description": "Unknown or cross-scope Subject or Operation", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/NotFoundProblem" } } } } }, "tags": [ "Workout acceptance" ], "operationId": "getWorkoutAcceptanceOperation" } }, "/v1/events": { "post": { "description": "Requires workout:write. Records one complete client-owned workout.completed snapshot and queues derived processing without changing canonical client history.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutCompletionRequest" } } } }, "responses": { "202": { "description": "Queued or exact replay.", "headers": { "Location": { "schema": { "type": "string" } }, "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutCompletionOperation" } } } }, "409": { "description": "Event, activity-revision, Idempotency-Key fingerprint, or Subject tombstone conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ConflictProblem" } } } }, "422": { "description": "Invalid snapshot, unavailable Subject, or stale revision." }, "429": { "description": "Tenant and workout-completion capability admission denied.", "headers": { "Retry-After": { "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 300 } } }, "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "const": "about:blank" }, "title": { "type": "string" }, "status": { "const": 429 }, "detail": { "enum": [ "operation_request_limit_exceeded", "operation_concurrency_limit_exceeded" ] } } } } } } }, "tags": [ "Workout completion" ], "operationId": "submitWorkoutCompletion", "summary": "Report one completed workout" } }, "/v1/subjects/{subject_ref}/workout-completion-operations/{operation_ref}": { "get": { "description": "Requires workout:read. Polls one Subject-scoped completion Operation.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "subject_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "operation_ref", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current Operation state.", "headers": { "Cache-Control": { "schema": { "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutCompletionOperation" } } } }, "404": { "description": "Missing or cross-scope Operation." } }, "tags": [ "Workout completion" ], "operationId": "getWorkoutCompletionOperation", "summary": "Poll a subject-scoped workout-completion Operation" } } }, "components": { "responses": { "OperationAdmissionRejected": { "description": "Tenant and capability request-rate or active-concurrency admission denied.", "headers": { "Retry-After": { "required": true, "schema": { "type": "integer", "minimum": 1, "maximum": 300 } } }, "content": { "application/problem+json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "const": "about:blank" }, "title": { "type": "string" }, "status": { "const": 429 }, "detail": { "enum": [ "operation_request_limit_exceeded", "operation_concurrency_limit_exceeded" ] } } } } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API token issued by the Kinellect team. Scopes are listed on each operation." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "schemas": { "RequestWorkoutAcceptance": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "selection" ], "properties": { "subject_ref": { "type": "string", "format": "uuid" }, "selection": { "$ref": "#/components/schemas/WorkoutAcceptanceSelection" } }, "examples": [ { "subject_ref": "77777777-7777-4777-8777-777777777777", "selection": { "source_kind": "standalone_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333", "action": "save", "local_date": null, "time_zone": null, "approval": "explicit_user_approval" } }, { "subject_ref": "77777777-7777-4777-8777-777777777777", "selection": { "source_kind": "standalone_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333", "action": "save_and_schedule", "local_date": "2026-09-10", "time_zone": "Europe/Oslo", "approval": "explicit_user_approval" } } ] }, "WorkoutAcceptanceSelection": { "type": "object", "additionalProperties": false, "required": [ "source_kind", "source_operation_ref", "source_ref", "action", "local_date", "time_zone", "approval" ], "properties": { "source_kind": { "enum": [ "standalone_generated", "daily_generated", "daily_existing" ] }, "source_operation_ref": { "type": "string", "format": "uuid" }, "source_ref": { "type": "string", "format": "uuid" }, "action": { "enum": [ "save", "save_and_schedule" ] }, "local_date": { "oneOf": [ { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "Strict YYYY-MM-DD calendar date; impossible dates are rejected." }, { "type": "null" } ] }, "time_zone": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "description": "Named Subject IANA time zone, including UTC. Numeric offsets and abbreviations are rejected. Must equal authoritative Subject context." }, { "type": "null" } ] }, "approval": { "enum": [ "explicit_user_approval", null ], "description": "Attests actual user approval of the exact enclosing Subject, source, action, date and time zone. Changing any bound selection requires new approval. Null does not satisfy confirmation_required." } }, "oneOf": [ { "properties": { "action": { "const": "save" }, "local_date": { "type": "null" }, "time_zone": { "type": "null" } } }, { "properties": { "action": { "const": "save_and_schedule" }, "local_date": { "type": "string", "format": "date", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "Strict YYYY-MM-DD calendar date; impossible dates are rejected." }, "time_zone": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Named Subject IANA time zone, including UTC. Numeric offsets and abbreviations are rejected. Must equal authoritative Subject context." } } } ], "description": "Acceptance is an explicit action. workout.save and workout.save_and_schedule require their own independently activated capability and connector support. auto_execute permits null approval; professional_review_required, proposal_only and rejected deny first execution even with approval. Caller and attestation bind the canonical request fingerprint. No replacement content or recovery fields are accepted." }, "WorkoutAcceptanceOutcome": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "receipt_ref", "workout_ref", "workout_content_version", "confirmed_at" ], "properties": { "status": { "const": "confirmed" }, "receipt_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "workout_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "workout_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "confirmed_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "receipt_ref", "workout_ref", "workout_content_version", "confirmed_at", "schedule_ref", "schedule_content_version" ], "properties": { "status": { "const": "confirmed" }, "receipt_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "workout_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "workout_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "confirmed_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." }, "schedule_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "schedule_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "safe_code" ], "properties": { "status": { "const": "conflict" }, "safe_code": { "enum": [ "schedule_conflict", "command_conflict" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "safe_code" ], "properties": { "status": { "const": "rejected" }, "safe_code": { "const": "action_rejected" } } } ], "description": "Only confirmed exposes real client receipt and effects. Scheduled references appear only for save_and_schedule. Inapplicable fields are omitted, never null. A conflict or rejection contains only status and safe_code." }, "WorkoutAcceptanceOperation": { "type": "object", "additionalProperties": false, "required": [ "operation_ref", "state", "result", "error_code", "error_message", "created_at", "finished_at" ], "properties": { "operation_ref": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "running", "completed", "failed", "cancelled", "expired" ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/WorkoutAcceptanceOutcome" }, { "type": "null" } ] }, "error_code": { "enum": [ "source_unavailable", "source_noncurrent", "capability_unavailable", "approval_required", "action_denied", "connector_unconfirmed", "execution_deadline_exceeded", "execution_attempts_exhausted", "operation_cancelled", "operation_expired", null ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." }, { "type": "null" } ] } }, "description": "One generic durable Operation lifecycle. completed contains exactly one confirmed, conflict or rejected business outcome. No unconfirmed business status exists. Unknown and cross-scope references are non-disclosing. Until a validated result commits, pending result and errors remain null. A terminal connector_unconfirmed failure has no result and cannot assure absence of a remote effect. Cancellation and expiry likewise do not prove absence of a remote effect. Execution-limit errors apply only before dispatch; exhaustion after possible dispatch without a validated result is connector_unconfirmed.", "oneOf": [ { "properties": { "state": { "const": "queued" }, "result": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "finished_at": { "type": "null" } } }, { "properties": { "state": { "const": "running" }, "result": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "finished_at": { "type": "null" } } }, { "properties": { "state": { "const": "completed" }, "result": { "$ref": "#/components/schemas/WorkoutAcceptanceOutcome" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "finished_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } }, { "properties": { "state": { "const": "failed" }, "result": { "type": "null" }, "error_code": { "enum": [ "source_unavailable", "source_noncurrent", "capability_unavailable", "approval_required", "action_denied", "connector_unconfirmed", "execution_deadline_exceeded", "execution_attempts_exhausted" ] }, "error_message": { "type": "string" }, "finished_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } }, { "properties": { "state": { "const": "cancelled" }, "result": { "type": "null" }, "error_code": { "const": "operation_cancelled" }, "error_message": { "const": "Workout acceptance was cancelled." }, "finished_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } }, { "properties": { "state": { "const": "expired" }, "result": { "type": "null" }, "error_code": { "const": "operation_expired" }, "error_message": { "const": "Workout acceptance expired." }, "finished_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } } ], "allOf": [ { "if": { "properties": { "error_code": { "const": "source_unavailable" } } }, "then": { "properties": { "error_message": { "const": "The workout source is unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "source_noncurrent" } } }, "then": { "properties": { "error_message": { "const": "The workout source is no longer current." } } } }, { "if": { "properties": { "error_code": { "const": "capability_unavailable" } } }, "then": { "properties": { "error_message": { "const": "The requested workout action is unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "approval_required" } } }, "then": { "properties": { "error_message": { "const": "Explicit user approval is required." } } } }, { "if": { "properties": { "error_code": { "const": "action_denied" } } }, "then": { "properties": { "error_message": { "const": "The requested workout action is not permitted." } } } }, { "if": { "properties": { "error_code": { "const": "connector_unconfirmed" } } }, "then": { "properties": { "error_message": { "const": "The client outcome could not be confirmed; the action may have taken effect." } } } }, { "if": { "properties": { "error_code": { "const": "execution_deadline_exceeded" } } }, "then": { "properties": { "error_message": { "const": "Workout acceptance exceeded its execution time limit." } } } }, { "if": { "properties": { "error_code": { "const": "execution_attempts_exhausted" } } }, "then": { "properties": { "error_message": { "const": "Workout acceptance exhausted its execution attempts." } } } }, { "if": { "properties": { "error_code": { "const": "operation_cancelled" } } }, "then": { "properties": { "error_message": { "const": "Workout acceptance was cancelled." } } } }, { "if": { "properties": { "error_code": { "const": "operation_expired" } } }, "then": { "properties": { "error_message": { "const": "Workout acceptance expired." } } } } ] }, "ActivateClientConfiguration": { "type": "object", "additionalProperties": false, "required": [ "client_description", "product_description", "coaching_domain", "tone", "terminology", "enabled_capabilities", "safety_policy", "action_policy", "connector_registration_ref" ], "properties": { "client_description": { "type": "string", "minLength": 1, "maxLength": 2000, "x-max-utf8-bytes": 2000 }, "product_description": { "type": "string", "minLength": 1, "maxLength": 2000, "x-max-utf8-bytes": 2000 }, "coaching_domain": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 }, "tone": { "enum": [ "supportive", "direct", "neutral" ] }, "terminology": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 } }, "enabled_capabilities": { "type": "array", "minItems": 1, "maxItems": 17, "uniqueItems": true, "items": { "enum": [ "conversation.respond", "daily.decide", "context.resolve", "exercise.search", "exercise.resolve", "workout.search", "workout.resolve", "workout.save", "workout.save_and_schedule", "workout.prescription.count", "workout.prescription.time", "workout.generate", "workout.warmup.generate", "workout.cooldown.generate", "preference.propose", "preference.update", "memory.preference.write" ] } }, "safety_policy": { "const": "fitness_coach_safety_v1" }, "action_policy": { "enum": [ "auto_execute", "confirmation_required", "professional_review_required", "proposal_only", "rejected" ] }, "connector_registration_ref": { "type": "string", "format": "uuid", "description": "Opaque reference to an operator-provisioned connector registration owned by this tenant environment." }, "workout_generation_policy": { "description": "Required and non-null when workout.generate is enabled; otherwise it may be omitted or null for backward-compatible non-generation configurations.", "oneOf": [ { "$ref": "#/components/schemas/WorkoutGenerationPolicy" }, { "type": "null" } ] }, "daily_decision_policy": { "oneOf": [ { "$ref": "#/components/schemas/DailyDecisionPolicy" }, { "type": "null" } ] }, "operation_admission_policies": { "type": "array", "maxItems": 6, "uniqueItems": true, "items": { "$ref": "#/components/schemas/OperationAdmissionPolicy" } }, "operation_usage_policies": { "type": "array", "maxItems": 6, "description": "Optional; omitted means an empty list. Each capability may appear at most once; a duplicate capability returns 422.", "items": { "$ref": "#/components/schemas/OperationUsagePolicy" } } }, "allOf": [ { "if": { "properties": { "enabled_capabilities": { "contains": { "const": "daily.decide" } } } }, "then": { "required": [ "daily_decision_policy" ], "properties": { "daily_decision_policy": { "$ref": "#/components/schemas/DailyDecisionPolicy" } } }, "else": { "properties": { "daily_decision_policy": { "type": "null" } } } }, { "if": { "required": [ "daily_decision_policy" ], "properties": { "daily_decision_policy": { "type": "object", "required": [ "workout_source_policy" ], "properties": { "workout_source_policy": { "const": "existing_only" } } } } }, "then": { "properties": { "enabled_capabilities": { "allOf": [ { "contains": { "const": "workout.search" } }, { "contains": { "const": "workout.resolve" } }, { "contains": { "const": "exercise.resolve" } } ], "anyOf": [ { "contains": { "const": "workout.prescription.count" } }, { "contains": { "const": "workout.prescription.time" } } ] } } } }, { "if": { "required": [ "daily_decision_policy" ], "properties": { "daily_decision_policy": { "type": "object", "required": [ "workout_source_policy" ], "properties": { "workout_source_policy": { "const": "generation_only" } } } } }, "then": { "properties": { "enabled_capabilities": { "allOf": [ { "contains": { "const": "workout.generate" } }, { "contains": { "const": "exercise.search" } }, { "contains": { "const": "exercise.resolve" } } ], "anyOf": [ { "contains": { "const": "workout.prescription.count" } }, { "contains": { "const": "workout.prescription.time" } } ] }, "workout_generation_policy": { "$ref": "#/components/schemas/WorkoutGenerationPolicy" } }, "required": [ "workout_generation_policy" ] } }, { "if": { "required": [ "daily_decision_policy" ], "properties": { "daily_decision_policy": { "type": "object", "required": [ "workout_source_policy" ], "properties": { "workout_source_policy": { "const": "existing_preferred" } } } } }, "then": { "properties": { "enabled_capabilities": { "allOf": [ { "contains": { "const": "workout.search" } }, { "contains": { "const": "workout.resolve" } }, { "contains": { "const": "workout.generate" } }, { "contains": { "const": "exercise.search" } }, { "contains": { "const": "exercise.resolve" } } ], "anyOf": [ { "contains": { "const": "workout.prescription.count" } }, { "contains": { "const": "workout.prescription.time" } } ] }, "workout_generation_policy": { "$ref": "#/components/schemas/WorkoutGenerationPolicy" } }, "required": [ "workout_generation_policy" ] } } ] }, "ClientConfigurationActivation": { "type": "object", "additionalProperties": false, "required": [ "configuration_ref", "configuration_version", "enabled_capabilities", "action_policy", "activated_at", "replayed" ], "properties": { "configuration_ref": { "type": "string", "format": "uuid" }, "configuration_version": { "type": "integer", "minimum": 1 }, "enabled_capabilities": { "type": "array", "items": { "type": "string" } }, "action_policy": { "type": "string" }, "activated_at": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean" } } }, "OperationAdmissionPolicy": { "type": "object", "additionalProperties": false, "required": [ "policy_version", "capability", "request_window_seconds", "soft_request_maximum", "hard_request_maximum", "soft_active_maximum", "hard_active_maximum", "hard_enforcement_enabled" ], "properties": { "policy_version": { "const": 1 }, "capability": { "enum": [ "conversation.respond", "daily.decide", "workout.generate", "workout.accept", "workout.complete", "coach_memory.compile" ] }, "request_window_seconds": { "type": "integer", "minimum": 1, "maximum": 86400 }, "soft_request_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "hard_request_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "soft_active_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "hard_active_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "hard_enforcement_enabled": { "type": "boolean" } } }, "OperationUsagePolicy": { "type": "object", "additionalProperties": false, "description": "Token and estimated-cost ceilings for one Operation capability, each set for a single Operation and for a day.", "required": [ "policy_version", "capability", "operation_token_maximum", "operation_estimated_cost_microunits_maximum", "daily_token_maximum", "daily_estimated_cost_microunits_maximum", "hard_enforcement_enabled" ], "properties": { "policy_version": { "const": 1 }, "capability": { "enum": [ "conversation.respond", "daily.decide", "workout.generate", "workout.accept", "workout.complete", "coach_memory.compile" ] }, "operation_token_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "operation_estimated_cost_microunits_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "daily_token_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000000 }, "daily_estimated_cost_microunits_maximum": { "type": "integer", "minimum": 1, "maximum": 1000000000000 }, "hard_enforcement_enabled": { "type": "boolean" } }, "examples": [ { "policy_version": 1, "capability": "conversation.respond", "operation_token_maximum": 10000, "operation_estimated_cost_microunits_maximum": 10000, "daily_token_maximum": 20000, "daily_estimated_cost_microunits_maximum": 20000, "hard_enforcement_enabled": true } ] }, "PutSubjectContext": { "type": "object", "additionalProperties": false, "required": [ "effective_at", "valid_through", "time_zone", "local_date", "primary_goal", "experience", "desired_sessions_per_week", "available_days", "unit_system", "equipment_refs", "safety_constraints", "completed_workouts", "mobility_summary", "recovery_summary" ], "properties": { "effective_at": { "type": "string", "format": "date-time", "description": "Must be strictly earlier than valid_through." }, "valid_through": { "type": "string", "format": "date-time", "description": "Exclusive currentness bound." }, "time_zone": { "type": "string" }, "local_date": { "type": "string", "format": "date" }, "primary_goal": { "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 1000 }, "experience": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 }, "desired_sessions_per_week": { "type": "integer", "minimum": 0, "maximum": 14 }, "available_days": { "type": "array", "maxItems": 7, "items": { "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] } }, "unit_system": { "enum": [ "metric", "imperial" ] }, "equipment_refs": { "type": "array", "maxItems": 50, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "safety_constraints": { "type": "array", "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 500 } }, "exercise_constraints": { "type": "array", "maxItems": 30, "items": { "$ref": "#/components/schemas/ExerciseConstraint" } }, "completed_workouts": { "type": "integer", "minimum": 0, "maximum": 1000 }, "mobility_summary": { "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 1000 }, "recovery_summary": { "type": "string", "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 1000 }, "blocker": { "type": [ "string", "null" ], "maxLength": 1000, "x-max-utf8-bytes": 1000 }, "daily_context": { "oneOf": [ { "$ref": "#/components/schemas/DailyContext" }, { "type": "null" } ] } } }, "ExerciseConstraint": { "type": "object", "additionalProperties": false, "required": [ "constraint_ref", "target", "effect", "state" ], "properties": { "constraint_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "target": { "type": "object", "additionalProperties": false, "required": [ "type", "value" ], "properties": { "type": { "enum": [ "exercise_ref", "safety_identifier" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } } }, "effect": { "enum": [ "hard_exclusion", "soft_avoidance" ] }, "state": { "enum": [ "active", "lifted" ] } } }, "SubjectContextWrite": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "context_ref", "context_version", "effective_at", "created_at", "replayed" ], "properties": { "subject_ref": { "type": "string", "format": "uuid" }, "context_ref": { "type": "string", "format": "uuid" }, "context_version": { "type": "integer", "minimum": 1 }, "effective_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "replayed": { "type": "boolean" } } }, "ConversationThread": { "type": "object", "additionalProperties": false, "required": [ "thread_ref", "subject_ref", "main", "created_at" ], "properties": { "thread_ref": { "type": "string", "format": "uuid" }, "subject_ref": { "type": "string", "format": "uuid" }, "main": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "ConversationTurn": { "type": "object", "additionalProperties": false, "required": [ "turn_ref", "sequence", "role", "message", "created_at", "assistant_schema_version" ], "properties": { "turn_ref": { "type": "string", "format": "uuid" }, "sequence": { "type": "integer", "minimum": 1 }, "role": { "const": "assistant" }, "message": { "type": "string", "minLength": 1, "maxLength": 16000 }, "created_at": { "type": "string", "format": "date-time" }, "assistant_schema_version": { "const": "conversation_grounding_v1" } } }, "ConversationOperation": { "oneOf": [ { "$ref": "#/components/schemas/QueuedOperation" }, { "$ref": "#/components/schemas/RunningOperation" }, { "$ref": "#/components/schemas/CompletedOperation" }, { "$ref": "#/components/schemas/FailedOperation" }, { "$ref": "#/components/schemas/CancelledOperation" }, { "$ref": "#/components/schemas/ExpiredOperation" } ] }, "OperationFields": { "type": "object", "additionalProperties": false, "required": [ "operation_ref", "state", "result", "error_code", "error_message", "fallback_text", "created_at", "finished_at", "action_receipts" ], "properties": { "operation_ref": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "running", "completed", "failed", "cancelled", "expired" ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/ConversationTurn" }, { "type": "null" } ] }, "error_code": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "fallback_text": { "type": [ "string", "null" ], "maxLength": 16000 }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" }, "action_receipts": { "type": "array", "items": { "$ref": "#/components/schemas/ConversationActionReceipt" } } } }, "ConversationActionReceipt": { "type": "object", "additionalProperties": false, "required": [ "tool", "outcome", "safe_code", "receipt_ref", "content_version", "outcome_text" ], "properties": { "tool": { "enum": [ "propose_preference_update", "update_preferences", "remember_explicit_preference" ] }, "outcome": { "enum": [ "succeeded", "failed", "proposed", "unconfirmed" ] }, "safe_code": { "type": "string" }, "receipt_ref": { "type": [ "string", "null" ], "maxLength": 200 }, "content_version": { "type": [ "string", "null" ], "maxLength": 200 }, "outcome_text": { "type": "string", "description": "Code-owned truthful rendering; never provider prose." } } }, "QueuedOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "queued" }, "result": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "fallback_text": { "type": "null" }, "finished_at": { "type": "null" } } } ] }, "RunningOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "running" }, "result": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "fallback_text": { "type": "null" }, "finished_at": { "type": "null" } } } ] }, "CompletedOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "completed" }, "result": { "$ref": "#/components/schemas/ConversationTurn" }, "error_code": { "type": "null" }, "error_message": { "type": "null" }, "fallback_text": { "type": "null" }, "finished_at": { "type": "string", "format": "date-time" } } } ] }, "FailedOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "failed" }, "result": { "type": "null" }, "error_code": { "enum": [ "provider_unavailable", "provider_invalid_response", "connector_unavailable", "client_configuration_missing", "subject_context_unavailable", "execution_deadline_exceeded", "execution_attempts_exhausted" ] }, "error_message": { "const": "The conversation response could not be completed safely." }, "fallback_text": { "type": [ "string", "null" ], "maxLength": 16000 }, "finished_at": { "type": "string", "format": "date-time" } } } ] }, "CancelledOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "cancelled" }, "result": { "type": "null" }, "error_code": { "const": "operation_cancelled" }, "error_message": { "const": "The conversation operation was cancelled before completion." }, "fallback_text": { "type": [ "string", "null" ], "maxLength": 16000 }, "finished_at": { "type": "string", "format": "date-time" } } } ] }, "ExpiredOperation": { "allOf": [ { "$ref": "#/components/schemas/OperationFields" }, { "type": "object", "properties": { "state": { "const": "expired" }, "result": { "type": "null" }, "error_code": { "const": "operation_expired" }, "error_message": { "const": "The conversation operation is no longer available." }, "fallback_text": { "type": [ "string", "null" ], "maxLength": 16000 }, "finished_at": { "type": "string", "format": "date-time" } } } ] }, "RequestWorkoutDraft": { "type": "object", "additionalProperties": false, "required": [ "subject_ref" ], "properties": { "subject_ref": { "type": "string", "format": "uuid" } } }, "WorkoutGenerationPolicy": { "type": "object", "additionalProperties": false, "required": [ "maximum_supersets", "maximum_exercises_per_superset", "maximum_total_exercises", "minimum_rest_before_seconds", "maximum_rest_before_seconds", "minimum_rest_between_cycles_seconds", "maximum_rest_between_cycles_seconds", "maximum_total_sets", "maximum_total_count_repetitions", "maximum_total_timed_work_seconds", "minimum_estimated_duration_seconds", "maximum_estimated_duration_seconds" ], "properties": { "maximum_supersets": { "type": "integer", "minimum": 1, "maximum": 20 }, "maximum_exercises_per_superset": { "type": "integer", "minimum": 1, "maximum": 20 }, "maximum_total_exercises": { "type": "integer", "minimum": 1, "maximum": 20 }, "minimum_rest_before_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "maximum_rest_before_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "minimum_rest_between_cycles_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "maximum_rest_between_cycles_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "maximum_total_sets": { "type": "integer", "minimum": 1, "maximum": 400 }, "maximum_total_count_repetitions": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 400000 }, "maximum_total_timed_work_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 2880000 }, "minimum_estimated_duration_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 604800 }, "maximum_estimated_duration_seconds": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 604800 } } }, "WorkoutDraft": { "type": "object", "additionalProperties": false, "required": [ "title", "warmup_supersets", "supersets", "cooldown_supersets" ], "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "warmup_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/WorkoutDraftSuperset" } }, "supersets": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/WorkoutDraftSuperset" } }, "cooldown_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/WorkoutDraftSuperset" } } } }, "WorkoutDraftSuperset": { "type": "object", "additionalProperties": false, "required": [ "order", "rest_between_cycles_seconds", "workout_exercises" ], "properties": { "order": { "type": "integer", "minimum": 1, "maximum": 20 }, "rest_between_cycles_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "workout_exercises": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/WorkoutDraftExercise" } } } }, "WorkoutDraftExercise": { "type": "object", "additionalProperties": false, "required": [ "exercise_ref", "exercise_content_version", "order", "sets", "rest_before_seconds", "prescription" ], "properties": { "exercise_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "exercise_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "order": { "type": "integer", "minimum": 1, "maximum": 20 }, "sets": { "type": "integer", "minimum": 1, "maximum": 20 }, "rest_before_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "prescription": { "oneOf": [ { "$ref": "#/components/schemas/CountPrescription" }, { "$ref": "#/components/schemas/TimePrescription" } ] } } }, "CountPrescription": { "type": "object", "additionalProperties": false, "required": [ "type", "repetitions" ], "properties": { "type": { "const": "count" }, "repetitions": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "TimePrescription": { "type": "object", "additionalProperties": false, "required": [ "type", "duration_seconds" ], "properties": { "type": { "const": "time" }, "duration_seconds": { "type": "integer", "minimum": 1, "maximum": 7200 } } }, "WorkoutGenerationOperation": { "type": "object", "additionalProperties": false, "required": [ "operation_ref", "state", "draft_ref", "draft", "error_code", "error_message", "catalog_version", "execution_mode", "validation_codes", "total_sets", "total_count_repetitions", "total_timed_work_seconds", "estimated_duration_seconds", "created_at", "finished_at" ], "properties": { "operation_ref": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "running", "completed", "failed", "cancelled", "expired" ] }, "draft_ref": { "type": [ "string", "null" ], "format": "uuid" }, "draft": { "oneOf": [ { "$ref": "#/components/schemas/WorkoutDraft" }, { "type": "null" } ] }, "error_code": { "enum": [ "client_configuration_unavailable", "subject_context_unavailable", "exercise_catalog_unavailable", "exercise_catalog_invalid", "empty_candidate_set", "provider_unavailable", "provider_invalid_response", "draft_validation_failed", "execution_mode_unavailable", "execution_deadline_exceeded", "execution_attempts_exhausted", "operation_cancelled", "operation_expired", "workout_generation_failed", null ] }, "error_message": { "description": "The workout draft could not be completed safely.", "oneOf": [ { "type": "null" }, { "type": "string", "const": "The workout draft could not be completed safely." } ] }, "catalog_version": { "type": [ "string", "null" ], "maxLength": 200 }, "execution_mode": { "enum": [ "deterministic", "real_ai" ] }, "validation_codes": { "type": "array", "uniqueItems": true, "items": { "enum": [ "validated", "regression_substitution", "constraint_conflict", "no_safe_alternative", "structure_invalid", "warmup_unsupported", "cooldown_unsupported", "exercise_missing", "exercise_changed", "exercise_inactive", "exercise_unavailable", "generation_facts_missing", "prescription_unsupported", "prescription_out_of_range", "equipment_incompatible", "safety_conflict", "rest_out_of_range", "volume_exceeded", "duration_unverifiable", "duration_out_of_range" ] } }, "total_sets": { "type": [ "integer", "null" ], "minimum": 0 }, "total_count_repetitions": { "type": [ "integer", "null" ], "minimum": 0 }, "total_timed_work_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "estimated_duration_seconds": { "type": [ "integer", "null" ], "minimum": 0 }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ConflictProblem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail" ], "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "const": 409 }, "detail": { "enum": [ "Conflict", "subject_deleted" ], "description": "subject_deleted means the Subject is deleted and must be reactivated before new Subject-owned requests. Conflict covers the other conflicts listed for the operation." } } }, "NotFoundProblem": { "type": "object", "additionalProperties": false, "required": [ "type", "title", "status", "detail" ], "example": { "type": "about:blank", "title": "Not Found", "status": 404, "detail": "Not Found" }, "properties": { "type": { "const": "about:blank" }, "title": { "const": "Not Found" }, "status": { "const": 404 }, "detail": { "const": "Not Found" } } }, "RequestDailyPlan": { "type": "object", "additionalProperties": false, "required": [ "subject_ref" ], "properties": { "subject_ref": { "type": "string", "format": "uuid" } } }, "DailyDecisionPolicy": { "type": "object", "additionalProperties": false, "required": [ "enabled_outcomes", "rest_fallback_codes", "recovery_max_age_seconds", "activity_max_age_seconds" ], "properties": { "enabled_outcomes": { "type": "array", "minItems": 1, "maxItems": 3, "uniqueItems": true, "items": { "enum": [ "workout", "rest", "mobility" ] } }, "workout_source_policy": { "enum": [ "existing_only", "existing_preferred", "generation_only" ] }, "non_workout_preference": { "enum": [ "rest", "mobility" ] }, "rest_fallback_codes": { "type": "array", "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "recovery_unavailable", "workout_content_unavailable" ] } }, "recovery_max_age_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 }, "activity_max_age_seconds": { "type": "integer", "minimum": 60, "maximum": 86400 } }, "oneOf": [ { "properties": { "enabled_outcomes": { "minItems": 1, "maxItems": 1, "items": { "enum": [ "rest" ] } }, "non_workout_preference": { "enum": [ "rest" ] }, "rest_fallback_codes": { "maxItems": 1, "items": { "enum": [ "recovery_unavailable" ] } } }, "required": [ "non_workout_preference" ], "allOf": [ { "not": { "required": [ "workout_source_policy" ] } } ] }, { "properties": { "enabled_outcomes": { "minItems": 1, "maxItems": 1, "items": { "enum": [ "mobility" ] } }, "non_workout_preference": { "enum": [ "mobility" ] }, "rest_fallback_codes": { "maxItems": 0 } }, "required": [ "non_workout_preference" ], "allOf": [ { "not": { "required": [ "workout_source_policy" ] } } ] }, { "properties": { "enabled_outcomes": { "minItems": 1, "maxItems": 1, "items": { "enum": [ "workout" ] } }, "workout_source_policy": { "enum": [ "existing_only", "existing_preferred", "generation_only" ] }, "rest_fallback_codes": { "maxItems": 0 } }, "required": [ "workout_source_policy" ], "allOf": [ { "not": { "required": [ "non_workout_preference" ] } } ] }, { "properties": { "enabled_outcomes": { "minItems": 2, "maxItems": 2, "items": { "enum": [ "rest", "mobility" ] } }, "non_workout_preference": { "enum": [ "rest", "mobility" ] }, "rest_fallback_codes": { "maxItems": 1, "items": { "enum": [ "recovery_unavailable" ] } } }, "required": [ "non_workout_preference" ], "allOf": [ { "not": { "required": [ "workout_source_policy" ] } } ] }, { "properties": { "enabled_outcomes": { "minItems": 2, "maxItems": 2, "items": { "enum": [ "workout", "rest" ] } }, "workout_source_policy": { "enum": [ "existing_only", "existing_preferred", "generation_only" ] }, "non_workout_preference": { "enum": [ "rest" ] }, "rest_fallback_codes": { "maxItems": 2, "items": { "enum": [ "recovery_unavailable", "workout_content_unavailable" ] } } }, "required": [ "workout_source_policy", "non_workout_preference" ] }, { "properties": { "enabled_outcomes": { "minItems": 2, "maxItems": 2, "items": { "enum": [ "workout", "mobility" ] } }, "workout_source_policy": { "enum": [ "existing_only", "existing_preferred", "generation_only" ] }, "non_workout_preference": { "enum": [ "mobility" ] }, "rest_fallback_codes": { "maxItems": 0 } }, "required": [ "workout_source_policy", "non_workout_preference" ] }, { "properties": { "enabled_outcomes": { "minItems": 3, "maxItems": 3, "items": { "enum": [ "workout", "rest", "mobility" ] } }, "workout_source_policy": { "enum": [ "existing_only", "existing_preferred", "generation_only" ] }, "non_workout_preference": { "enum": [ "rest", "mobility" ] }, "rest_fallback_codes": { "maxItems": 2, "items": { "enum": [ "recovery_unavailable", "workout_content_unavailable" ] } } }, "required": [ "workout_source_policy", "non_workout_preference" ] } ], "description": "Seven enabled-outcome subsets. Conditional fields must be omitted when inapplicable; explicit null is invalid. Choices follow the deterministic table in ADR 0009. Existing-only requires workout.search, workout.resolve, exercise.resolve and a supported prescription. Generation-only requires workout.generate, exercise.search, exercise.resolve, a supported prescription and the existing generation policy. Existing-preferred requires both bundles." }, "DailyContext": { "type": "object", "additionalProperties": false, "required": [ "week_start", "history_through", "completed_workout_dates", "completed_mobility_dates", "preferred_days", "recovery_state", "recovery_observed_at", "recovery_valid_through" ], "properties": { "week_start": { "type": "string", "format": "date" }, "history_through": { "type": "string", "format": "date-time" }, "completed_workout_dates": { "type": "array", "maxItems": 28, "items": { "type": "string", "format": "date" } }, "completed_mobility_dates": { "type": "array", "maxItems": 28, "items": { "type": "string", "format": "date" } }, "preferred_days": { "type": "array", "maxItems": 7, "uniqueItems": true, "items": { "type": "integer", "minimum": 1, "maximum": 7 } }, "recovery_state": { "enum": [ "ready", "mobility_only", "rest_only", "unknown" ] }, "recovery_observed_at": { "type": "string", "format": "date-time" }, "recovery_valid_through": { "type": "string", "format": "date-time" } }, "description": "week_start is the Monday containing parent local_date in its IANA time_zone. Convert history_through to that time_zone before deriving the inclusive history interval from week_start minus seven local calendar days through the local date of history_through, which cannot exceed parent local_date. Repeated completion dates represent separate sessions, with at most 28 entries in each completion list. Only current-week workout entries count toward the weekly target; mobility entries do not. Preferred ISO weekdays are unique and must be a subset of parent available_days. Recovery observed_at < valid_through. Admission requires matching current local date, effective_at <= now < valid_through and history_through <= now < history_through + activity_max_age_seconds. Recovery is usable only for ready, mobility_only or rest_only with observed_at <= now < min(recovery_valid_through, observed_at + recovery_max_age_seconds). These cross-field calendar, timezone and freshness relations are enforced by the application. Date-only entries assert session completeness through history_through without inventing intra-day timestamps; a completed workout today prevents selection of another workout." }, "DailyExistingWorkoutExercise": { "type": "object", "additionalProperties": false, "required": [ "exercise_ref", "exercise_content_version", "order", "sets", "rest_before_seconds", "prescription_type", "prescription_value" ], "properties": { "exercise_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "exercise_content_version": { "type": "string", "minLength": 1, "maxLength": 200 }, "order": { "type": "integer", "minimum": 1, "maximum": 20 }, "sets": { "type": "integer", "minimum": 1, "maximum": 20 }, "rest_before_seconds": { "type": "integer", "minimum": 0, "maximum": 3600 }, "prescription_type": { "enum": [ "count", "time" ] }, "prescription_value": { "type": "integer", "minimum": 1, "maximum": 7200 } }, "allOf": [ { "if": { "properties": { "prescription_type": { "const": "count" } } }, "then": { "properties": { "prescription_value": { "maximum": 1000 } } } } ] }, "DailyExistingWorkout": { "type": "object", "additionalProperties": false, "required": [ "workout_ref", "catalog_version", "warmup_supersets", "supersets", "cooldown_supersets" ], "properties": { "workout_ref": { "type": "string", "minLength": 1, "maxLength": 200 }, "catalog_version": { "type": "string", "minLength": 1, "maxLength": 200 }, "warmup_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/DailyExistingWorkoutSuperset" } }, "supersets": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/DailyExistingWorkoutSuperset" } }, "cooldown_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/DailyExistingWorkoutSuperset" } } } }, "DailyExistingWorkoutSuperset": { "type": "object", "additionalProperties": false, "required": [ "order", "workout_exercises" ], "properties": { "order": { "type": "integer", "minimum": 1, "maximum": 20 }, "workout_exercises": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/DailyExistingWorkoutExercise" } } } }, "DailyPlanDecision": { "type": "object", "additionalProperties": false, "required": [ "decision_ref", "configuration_ref", "context_ref", "configuration_version", "context_version", "schema_version", "outcome", "reason_codes", "reason_text", "sources", "workout_source", "existing_workout", "existing_workout_verified_at", "existing_workout_catalog_version", "generated_workout", "workout_generation_execution_mode", "generation_execution_mode", "generation_provider", "generation_model", "generation_schema_version", "generation_catalog_version", "decided_at", "local_date", "week_start", "time_zone", "policy_fingerprint" ], "properties": { "decision_ref": { "type": "string", "format": "uuid" }, "configuration_ref": { "type": "string", "format": "uuid" }, "context_ref": { "type": "string", "format": "uuid" }, "configuration_version": { "type": "integer", "minimum": 1 }, "context_version": { "type": "integer", "minimum": 1 }, "schema_version": { "const": 1 }, "outcome": { "enum": [ "workout", "rest", "mobility" ] }, "reason_codes": { "type": "array", "minItems": 1, "maxItems": 17, "uniqueItems": true, "items": { "enum": [ "weekly_target_met", "workout_completed_today", "preferred_workout_day", "deferred_to_preferred_day", "target_at_risk", "target_unattainable", "day_unavailable", "workout_disabled", "recovery_rest_only", "recovery_mobility_only", "context_blocker", "recovery_unavailable", "non_workout_preference", "only_eligible_non_workout", "existing_workout_verified", "generated_workout_validated", "workout_content_unavailable" ] } }, "reason_text": { "type": "string", "minLength": 1, "maxLength": 4000 }, "sources": { "type": "array", "minItems": 1, "maxItems": 13, "items": { "type": "object", "additionalProperties": false, "required": [ "code", "reference", "version", "fields" ], "properties": { "code": { "enum": [ "daily_policy", "activity_history", "availability", "recovery", "context_blocker", "existing_workout", "generated_workout", "preference_memory", "primary_goal", "equipment" ] }, "reference": { "type": "string", "minLength": 1, "maxLength": 200 }, "version": { "type": "string", "minLength": 1, "maxLength": 200 }, "fields": { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "maxItems": 4 } }, "allOf": [ { "if": { "properties": { "code": { "const": "daily_policy" } } }, "then": { "properties": { "fields": { "const": [ "daily_decision_policy" ] } } } }, { "if": { "properties": { "code": { "const": "activity_history" } } }, "then": { "properties": { "fields": { "const": [ "desired_sessions_per_week", "daily_context.week_start", "daily_context.history_through", "daily_context.completed_workout_dates" ] } } } }, { "if": { "properties": { "code": { "const": "availability" } } }, "then": { "properties": { "fields": { "const": [ "available_days", "daily_context.preferred_days", "local_date", "time_zone" ] } } } }, { "if": { "properties": { "code": { "const": "recovery" } } }, "then": { "properties": { "fields": { "const": [ "daily_context.recovery_state", "daily_context.recovery_observed_at", "daily_context.recovery_valid_through" ] } } } }, { "if": { "properties": { "code": { "const": "context_blocker" } } }, "then": { "properties": { "fields": { "const": [ "blocker" ] } } } }, { "if": { "properties": { "code": { "const": "existing_workout" } } }, "then": { "properties": { "fields": { "const": [ "supersets" ] } } } }, { "if": { "properties": { "code": { "const": "generated_workout" } } }, "then": { "properties": { "fields": { "const": [ "draft" ] } } } }, { "if": { "properties": { "code": { "const": "preference_memory" } } }, "then": { "properties": { "fields": { "const": [ "preference_name", "text", "source_turn_ref" ] } } } }, { "if": { "properties": { "code": { "const": "primary_goal" } } }, "then": { "properties": { "fields": { "const": [ "primary_goal" ] } } } }, { "if": { "properties": { "code": { "const": "equipment" } } }, "then": { "properties": { "fields": { "const": [ "equipment_refs" ] } } } } ] } }, "workout_source": { "enum": [ "existing_workout", "generated_workout", null ] }, "existing_workout": { "oneOf": [ { "$ref": "#/components/schemas/DailyExistingWorkout" }, { "type": "null" } ] }, "existing_workout_verified_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "existing_workout_catalog_version": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "generated_workout": { "oneOf": [ { "$ref": "#/components/schemas/WorkoutDraft" }, { "type": "null" } ] }, "workout_generation_execution_mode": { "enum": [ "deterministic", "real_ai", null ] }, "generation_execution_mode": { "enum": [ "deterministic", "real_ai", null ] }, "generation_provider": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "generation_model": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "generation_schema_version": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "generation_catalog_version": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "decided_at": { "type": "string", "format": "date-time" }, "local_date": { "type": "string", "format": "date" }, "week_start": { "type": "string", "format": "date" }, "time_zone": { "type": "string", "minLength": 1, "maxLength": 100 }, "policy_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "description": "Immutable safe result. decided_at and receipt verification use application time; Operation lifecycle uses native time. Never compare these clock domains. decided_at in time_zone must equal local_date. Polling never rewrites this document. Memory evidence appears only for actual generation. Source fields are code-owned pinned evidence.", "oneOf": [ { "properties": { "workout_source": { "const": null }, "outcome": { "enum": [ "rest", "mobility" ] }, "generated_workout": { "type": "null" }, "generation_execution_mode": { "type": "null" }, "generation_provider": { "type": "null" }, "generation_model": { "type": "null" }, "generation_schema_version": { "type": "null" }, "generation_catalog_version": { "type": "null" }, "existing_workout": { "type": "null" }, "existing_workout_verified_at": { "type": "null" }, "existing_workout_catalog_version": { "type": "null" } } }, { "properties": { "workout_source": { "const": "existing_workout" }, "outcome": { "enum": [ "workout" ] }, "generated_workout": { "type": "null" }, "generation_execution_mode": { "type": "null" }, "generation_provider": { "type": "null" }, "generation_model": { "type": "null" }, "generation_schema_version": { "type": "null" }, "generation_catalog_version": { "type": "null" }, "existing_workout": { "not": { "type": "null" } }, "existing_workout_verified_at": { "not": { "type": "null" } }, "existing_workout_catalog_version": { "not": { "type": "null" } } } }, { "properties": { "workout_source": { "const": "generated_workout" }, "outcome": { "enum": [ "workout" ] }, "generated_workout": { "not": { "type": "null" } }, "generation_execution_mode": { "not": { "type": "null" } }, "generation_provider": { "not": { "type": "null" } }, "generation_model": { "not": { "type": "null" } }, "generation_schema_version": { "not": { "type": "null" } }, "generation_catalog_version": { "not": { "type": "null" } }, "existing_workout": { "type": "null" }, "existing_workout_verified_at": { "type": "null" }, "existing_workout_catalog_version": { "type": "null" }, "workout_generation_execution_mode": { "enum": [ "real_ai", "deterministic" ] } } } ], "allOf": [ { "if": { "properties": { "workout_source": { "const": "generated_workout" }, "workout_generation_execution_mode": { "const": "deterministic" } } }, "then": { "properties": { "generation_execution_mode": { "const": "deterministic" } } } }, { "if": { "properties": { "workout_source": { "const": "generated_workout" }, "workout_generation_execution_mode": { "const": "real_ai" } } }, "then": { "properties": { "generation_execution_mode": { "const": "real_ai" } } } }, { "if": { "properties": { "workout_source": { "const": "existing_workout" } } }, "then": { "properties": { "reason_codes": { "contains": { "const": "existing_workout_verified" } } } }, "else": { "properties": { "reason_codes": { "not": { "contains": { "const": "existing_workout_verified" } } } } } }, { "if": { "properties": { "workout_source": { "const": "generated_workout" } } }, "then": { "properties": { "reason_codes": { "contains": { "const": "generated_workout_validated" } } } }, "else": { "properties": { "reason_codes": { "not": { "contains": { "const": "generated_workout_validated" } } } } } } ] }, "DailyPlanOperation": { "type": "object", "additionalProperties": false, "required": [ "operation_ref", "state", "result", "error_code", "error_message", "currentness", "created_at", "finished_at" ], "properties": { "operation_ref": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "running", "completed", "failed", "cancelled", "expired" ] }, "result": { "oneOf": [ { "$ref": "#/components/schemas/DailyPlanDecision" }, { "type": "null" } ] }, "error_code": { "enum": [ "client_configuration_unavailable", "subject_context_unavailable", "local_date_changed", "activity_history_unavailable", "recovery_unavailable", "no_eligible_outcome", "workout_content_unavailable", "connector_unavailable", "connector_invalid_response", "provider_unavailable", "provider_invalid_response", "execution_mode_unavailable", "execution_deadline_exceeded", "execution_attempts_exhausted", "operation_cancelled", "operation_expired", "decision_contract_invalid", null ] }, "error_message": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "currentness": { "enum": [ "current", "context_unavailable", "context_changed", "local_date_changed", "configuration_changed", "activity_expired", "recovery_changed", null ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] } }, "oneOf": [ { "properties": { "state": { "const": "queued" }, "finished_at": { "type": "null" }, "result": { "type": "null" }, "currentness": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" } } }, { "properties": { "state": { "const": "running" }, "finished_at": { "type": "null" }, "result": { "type": "null" }, "currentness": { "type": "null" }, "error_code": { "type": "null" }, "error_message": { "type": "null" } } }, { "properties": { "state": { "const": "completed" }, "finished_at": { "type": "string", "format": "date-time" }, "result": { "$ref": "#/components/schemas/DailyPlanDecision" }, "currentness": { "enum": [ "current", "context_unavailable", "context_changed", "local_date_changed", "configuration_changed", "activity_expired", "recovery_changed" ] }, "error_code": { "type": "null" }, "error_message": { "type": "null" } } }, { "properties": { "state": { "const": "failed" }, "finished_at": { "type": "string", "format": "date-time" }, "result": { "type": "null" }, "currentness": { "type": "null" }, "error_code": { "enum": [ "client_configuration_unavailable", "subject_context_unavailable", "local_date_changed", "activity_history_unavailable", "recovery_unavailable", "no_eligible_outcome", "workout_content_unavailable", "connector_unavailable", "connector_invalid_response", "provider_unavailable", "provider_invalid_response", "execution_mode_unavailable", "execution_deadline_exceeded", "execution_attempts_exhausted", "operation_cancelled", "operation_expired", "decision_contract_invalid" ] }, "error_message": { "type": "string", "minLength": 1, "maxLength": 200 } } }, { "properties": { "state": { "const": "cancelled" }, "finished_at": { "type": "string", "format": "date-time" }, "result": { "type": "null" }, "currentness": { "type": "null" }, "error_code": { "const": "operation_cancelled" }, "error_message": { "type": "string", "minLength": 1, "maxLength": 200 } } }, { "properties": { "state": { "const": "expired" }, "finished_at": { "type": "string", "format": "date-time" }, "result": { "type": "null" }, "currentness": { "type": "null" }, "error_code": { "const": "operation_expired" }, "error_message": { "type": "string", "minLength": 1, "maxLength": 200 } } } ], "allOf": [ { "if": { "properties": { "error_code": { "const": "client_configuration_unavailable" } } }, "then": { "properties": { "error_message": { "const": "An active daily coaching configuration is required." } } } }, { "if": { "properties": { "error_code": { "const": "subject_context_unavailable" } } }, "then": { "properties": { "error_message": { "const": "Current subject context is required." } } } }, { "if": { "properties": { "error_code": { "const": "local_date_changed" } } }, "then": { "properties": { "error_message": { "const": "Request a new daily plan for the current local date." } } } }, { "if": { "properties": { "error_code": { "const": "activity_history_unavailable" } } }, "then": { "properties": { "error_message": { "const": "Current activity history is required." } } } }, { "if": { "properties": { "error_code": { "const": "recovery_unavailable" } } }, "then": { "properties": { "error_message": { "const": "Current recovery information is required." } } } }, { "if": { "properties": { "error_code": { "const": "no_eligible_outcome" } } }, "then": { "properties": { "error_message": { "const": "The daily policy and current context permit no daily outcome." } } } }, { "if": { "properties": { "error_code": { "const": "workout_content_unavailable" } } }, "then": { "properties": { "error_message": { "const": "Suitable workout content is unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "connector_unavailable" } } }, "then": { "properties": { "error_message": { "const": "The client connector is temporarily unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "connector_invalid_response" } } }, "then": { "properties": { "error_message": { "const": "The client connector returned unusable information." } } } }, { "if": { "properties": { "error_code": { "const": "provider_unavailable" } } }, "then": { "properties": { "error_message": { "const": "Workout generation is temporarily unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "provider_invalid_response" } } }, "then": { "properties": { "error_message": { "const": "Workout generation returned an unusable result." } } } }, { "if": { "properties": { "error_code": { "const": "execution_mode_unavailable" } } }, "then": { "properties": { "error_message": { "const": "The requested workout generation setting is unavailable." } } } }, { "if": { "properties": { "error_code": { "const": "execution_deadline_exceeded" } } }, "then": { "properties": { "error_message": { "const": "The daily plan execution deadline was exceeded." } } } }, { "if": { "properties": { "error_code": { "const": "execution_attempts_exhausted" } } }, "then": { "properties": { "error_message": { "const": "The daily plan execution attempt limit was reached." } } } }, { "if": { "properties": { "error_code": { "const": "operation_cancelled" } } }, "then": { "properties": { "error_message": { "const": "The daily plan operation was cancelled." } } } }, { "if": { "properties": { "error_code": { "const": "operation_expired" } } }, "then": { "properties": { "error_message": { "const": "The daily plan operation has expired." } } } }, { "if": { "properties": { "error_code": { "const": "decision_contract_invalid" } } }, "then": { "properties": { "error_message": { "const": "A valid daily decision could not be established." } } } } ] }, "WorkoutCompletionRequest": { "type": "object", "additionalProperties": false, "required": [ "event_ref", "event_type", "schema_version", "subject_ref", "activity_ref", "activity_revision", "occurred_at", "workout_ref", "duration_seconds", "exercise_results", "feedback" ], "properties": { "event_ref": { "type": "string", "format": "uuid" }, "event_type": { "const": "workout.completed" }, "schema_version": { "const": 1 }, "subject_ref": { "type": "string", "format": "uuid" }, "activity_ref": { "type": "string", "minLength": 1, "maxLength": 255 }, "activity_revision": { "type": "integer", "minimum": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "workout_ref": { "type": "string", "minLength": 1, "maxLength": 255 }, "duration_seconds": { "type": "integer", "minimum": 0, "maximum": 604800 }, "exercise_results": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/WorkoutExerciseResult" } }, "feedback": { "$ref": "#/components/schemas/WorkoutFeedback" } } }, "WorkoutExerciseResult": { "type": "object", "additionalProperties": false, "required": [ "exercise_ref", "exercise_content_version", "status", "prescription_type", "prescribed_value", "completed_value" ], "properties": { "exercise_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "exercise_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "status": { "enum": [ "performed", "skipped" ] }, "prescription_type": { "enum": [ "count", "time" ] }, "prescribed_value": { "type": "integer", "minimum": 1 }, "completed_value": { "type": [ "integer", "null" ], "minimum": 0 } } }, "WorkoutFeedback": { "type": "object", "additionalProperties": false, "required": [ "rating", "note" ], "properties": { "rating": { "enum": [ "positive", "neutral", "tough" ] }, "note": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2000 } } }, "WorkoutCompletionOperation": { "type": "object", "additionalProperties": false, "required": [ "operation_ref", "state", "activity_ref", "activity_revision", "currentness", "reaction", "notification_suggested", "error_code", "error_message", "created_at", "finished_at" ], "properties": { "operation_ref": { "type": "string", "format": "uuid" }, "state": { "enum": [ "queued", "running", "completed", "failed", "cancelled", "expired" ] }, "activity_ref": { "type": "string" }, "activity_revision": { "type": "integer", "minimum": 1 }, "currentness": { "enum": [ "current", "superseded" ], "description": "Superseded results never expose reaction or notification fields." }, "reaction": { "type": [ "string", "null" ], "description": "Present only for a current completed Operation; null for every other lifecycle state." }, "notification_suggested": { "type": [ "boolean", "null" ], "description": "Present only for a current completed Operation; null for every other lifecycle state." }, "error_code": { "type": [ "string", "null" ], "enum": [ "model_failed", "operation_cancelled", "operation_expired", null ] }, "error_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "finished_at": { "type": [ "string", "null" ], "format": "date-time" } } } } }, "servers": [ { "url": "https://{kinellect_host}", "description": "Your Kinellect environment. The host is issued during onboarding.", "variables": { "kinellect_host": { "default": "api.kinellect.com", "description": "Issued during onboarding." } } } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Configuration", "description": "Activate immutable, versioned client configurations." }, { "name": "Subject context", "description": "Store the authoritative facts about a user that coaching relies on." }, { "name": "Subject lifecycle", "description": "Delete a user (tombstone and cancel their work) or reactivate a deleted user." }, { "name": "Conversation", "description": "Threads, Turns and conversation Operations. Creating a Thread also registers the user." }, { "name": "Workout drafts", "description": "Validated workout proposals built from your catalog." }, { "name": "Daily plans", "description": "Deterministic daily workout, rest or mobility decisions." }, { "name": "Workout acceptance", "description": "Save or schedule a proposed workout through your connector after explicit approval." }, { "name": "Workout completion", "description": "Report completed workouts and receive a coach reaction." } ] }