{ "openapi": "3.1.0", "info": { "title": "Kinellect Connector API (implemented by you)", "version": "1.0.0", "description": "The Connector API is the set of HTTPS endpoints that **your** service implements and **Kinellect** calls.\nKinellect never reads your database. Every fact it needs about a user (current context), your content\n(exercises and workouts) and every action it takes on your side (saving a preference, saving or scheduling\na workout) goes through these endpoints.\n\n**Transport rules that apply to every endpoint**\n\n- Kinellect calls `{your connector base URL}` + the fixed path shown for each operation. You register one HTTPS\n base URL and one bearer secret with Kinellect during onboarding. No per-endpoint URLs are configurable.\n- Every request carries `Authorization: Bearer `, `Accept: application/json`,\n `Accept-Encoding: identity`, `Content-Type: application/json` and `X-Kinellect-Tenant: `.\n Mutating actions also carry `Idempotency-Key`.\n- Reply with HTTP 2xx and a JSON **object** body. Any other status is treated as a failure.\n- **Responses must contain exactly the documented keys.** Kinellect compares the complete key set of every\n object. A missing key *or an extra key* makes the whole response invalid. Optional keys are either present\n or absent as documented; they are never replaced by `null` unless the schema says the value is nullable.\n- Do not compress responses (`Content-Encoding` must be absent or `identity`), do not redirect (redirects are\n not followed), keep bodies at or below 131072 bytes and never include NUL characters.\n- String limits are UTF-8 **byte** lengths, not character counts. Empty strings are invalid unless stated.\n- Kinellect waits at most 2 seconds for a connection or between bytes and at most 5 seconds per attempt. It\n retries **once** after HTTP 408, 429, 502, 503, 504 or a network failure, honouring `Retry-After` between\n 0.1 and 1 second, and only while the calling operation's deadline allows it. Make endpoints fast and\n idempotent.\n- `subject_ref` in every request is the **Kinellect subject reference** (a UUID) that Kinellect returned when\n you created the user's first Conversation Thread. Keep a mapping from your own user id to this value.\n" }, "paths": { "/ai-coach-connector/v1/capabilities": { "get": { "summary": "Declare the connector contract version and supported capabilities", "description": "Called when a client configuration version is activated, with a 10 second deadline. A failed, timed-out or invalid response makes activation return 503. Activation returns 422 when contract_version differs from the registered connector contract version or when an enabled connector capability (context.resolve, exercise.search, exercise.resolve, workout.search, workout.resolve, workout.save, workout.save_and_schedule, workout.prescription.count, workout.prescription.time or preference.update) is absent from capabilities.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "responses": { "200": { "description": "Connector capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCapabilities" }, "examples": { "capabilities": { "value": { "contract_version": 1, "content_version": "catalog-2026-09-20", "capabilities": [ "context.resolve", "exercise.search", "exercise.resolve", "workout.prescription.count", "workout.prescription.time", "preference.update" ] } } } } } } }, "operationId": "getConnectorCapabilities", "tags": [ "Discovery" ] } }, "/ai-coach-connector/v1/context/resolve": { "post": { "summary": "Return the Subject's current authoritative context", "description": "Return the same facts that PUT /v1/subjects/{subject_ref}/context/{context_version} accepts, plus context_version, content_version and provenance. Return {\"available\": false} with no other key when no context exists; available: true is invalid. daily_context and exercise_constraints are optional keys; daily_context may also be null.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubjectRequest" }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10" } } } }, "responses": { "200": { "description": "Current context or explicit unavailability", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ResolvedSubjectContext" }, { "$ref": "#/components/schemas/SubjectContextUnavailable" } ] }, "examples": { "available": { "value": { "context_version": 12, "content_version": "profile-2026-09-24", "provenance": "client_profile", "effective_at": "2026-09-25T05:00:00Z", "valid_through": "2026-09-26T05:00:00Z", "time_zone": "Europe/Oslo", "local_date": "2026-09-25", "primary_goal": "Build pain-free pulling strength over 8 weeks", "experience": "beginner", "desired_sessions_per_week": 3, "available_days": [ "monday", "wednesday", "friday" ], "unit_system": "metric", "equipment_refs": [ "resistance-band", "pull-up-bar" ], "safety_constraints": [ "avoid-overhead-loading" ], "completed_workouts": 14, "mobility_summary": "Limited shoulder flexion on the left side", "recovery_summary": "Sleeping well, no soreness reported", "blocker": null } }, "available_with_optional_keys": { "value": { "context_version": 13, "content_version": "profile-2026-09-25", "provenance": "client_profile", "effective_at": "2026-09-25T05:00:00+00:00", "valid_through": "2026-09-26T05:00:00+00:00", "time_zone": "Europe/Oslo", "local_date": "2026-09-25", "primary_goal": "Build pain-free pulling strength over 8 weeks", "experience": "beginner", "desired_sessions_per_week": 3, "available_days": [ "monday", "wednesday", "friday" ], "unit_system": "metric", "equipment_refs": [ "resistance-band", "pull-up-bar" ], "safety_constraints": [ "avoid-overhead-loading" ], "completed_workouts": 14, "mobility_summary": "Limited shoulder flexion on the left side", "recovery_summary": "Sleeping well, no soreness reported", "blocker": "Wait for clearance after the shoulder check-up", "daily_context": { "week_start": "2026-09-21", "history_through": "2026-09-25T05:00:00Z", "completed_workout_dates": [ "2026-09-21", "2026-09-23" ], "completed_mobility_dates": [ "2026-09-16" ], "preferred_days": [ 1, 3, 5 ], "recovery_state": "ready", "recovery_observed_at": "2026-09-25T05:00:00Z", "recovery_valid_through": "2026-09-26T05:00:00Z" }, "exercise_constraints": [ { "constraint_ref": "shoulder-overhead", "target": { "type": "safety_identifier", "value": "overhead-loading" }, "effect": "hard_exclusion", "state": "active" } ] } }, "unavailable": { "value": { "available": false } } } } } } }, "operationId": "resolveSubjectContext", "tags": [ "Context" ] } }, "/ai-coach-connector/v1/content/exercises/search": { "post": { "summary": "Search the exercise catalog for one Subject", "description": "Return at most 20 exercises matching a free-text query written by Kinellect.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "query" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" }, "query": { "type": "string", "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 500 } } }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10", "query": "scapular pull" } } } }, "responses": { "200": { "description": "Matching exercises from one catalog version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExerciseCatalogResult" }, "examples": { "with_optional_facts": { "value": { "content_version": "catalog-2026-09-20", "exercises": [ { "exercise_ref": "scapular-pull-up", "display_name": "Scapular pull-up", "movement_pattern": "vertical_pull", "equipment_refs": [ "pull-up-bar" ], "verification_facts": { "item_content_version": "v7", "active": true, "available": true, "prescription_types": [ "count" ], "safety_identifiers": [], "generation_facts": { "minimum_count": 5, "maximum_count": 15, "count_duration_seconds_per_repetition": 3, "minimum_duration_seconds": null, "maximum_duration_seconds": null } }, "relationships": { "progression_refs": [ "pull-up" ], "regression_refs": [ "band-pull-apart" ], "related_refs": [] } } ] } }, "projection_only": { "value": { "content_version": "catalog-2026-09-20", "exercises": [ { "exercise_ref": "band-pull-apart", "display_name": "Band pull-apart", "movement_pattern": "horizontal_pull", "equipment_refs": [ "resistance-band" ] } ] } } } } } } }, "operationId": "searchExercises", "tags": [ "Content" ] } }, "/ai-coach-connector/v1/content/exercises/resolve": { "post": { "summary": "Resolve exercises by reference", "description": "Return the current projection of the requested exercises; omit references that are unknown.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "exercise_refs" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" }, "exercise_refs": { "type": "array", "minItems": 1, "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } } } }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10", "exercise_refs": [ "scapular-pull-up", "dead-hang" ] } } } }, "responses": { "200": { "description": "Resolved exercises from one catalog version", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExerciseCatalogResult" }, "examples": { "resolved": { "value": { "content_version": "catalog-2026-09-20", "exercises": [ { "exercise_ref": "scapular-pull-up", "display_name": "Scapular pull-up", "movement_pattern": "vertical_pull", "equipment_refs": [ "pull-up-bar" ], "verification_facts": { "item_content_version": "v7", "active": true, "available": true, "prescription_types": [ "count" ], "safety_identifiers": [] } }, { "exercise_ref": "dead-hang", "display_name": "Dead hang", "movement_pattern": "hang", "equipment_refs": [ "pull-up-bar" ], "verification_facts": { "item_content_version": "v2", "active": true, "available": true, "prescription_types": [ "time" ], "safety_identifiers": [ "grip-load" ], "generation_facts": { "minimum_count": null, "maximum_count": null, "count_duration_seconds_per_repetition": null, "minimum_duration_seconds": 10, "maximum_duration_seconds": 60 } } } ] } } } } } } }, "operationId": "resolveExercises", "tags": [ "Content" ] } }, "/ai-coach-connector/v1/content/workouts/search": { "post": { "summary": "Search existing workouts", "description": "Return at most limit unique workout references from one catalog version. The request carries no cursor.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "query", "limit" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" }, "query": { "type": "string", "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 500 }, "limit": { "type": "integer", "minimum": 1, "maximum": 20 } } }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10", "query": "upper body beginner", "limit": 3 } } } }, "responses": { "200": { "description": "One page of workout references", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutSearchPage" }, "examples": { "page": { "value": { "catalog_version": "workouts-2026-09-20", "workout_refs": [ "upper-a", "upper-b" ], "next_cursor": null } } } } } } }, "operationId": "searchWorkouts", "tags": [ "Content" ] } }, "/ai-coach-connector/v1/content/workouts/resolve": { "post": { "summary": "Resolve one existing workout", "description": "Return status resolved with the full workout, or missing, inactive or changed with workout null.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "workout_ref", "expected_catalog_version" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" }, "workout_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "expected_catalog_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } } }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10", "workout_ref": "upper-a", "expected_catalog_version": "workouts-2026-09-20" } } } }, "responses": { "200": { "description": "Resolution outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutResolution" }, "examples": { "resolved": { "value": { "status": "resolved", "workout": { "workout_ref": "upper-a", "catalog_version": "workouts-2026-09-20", "warmup_supersets": [ { "order": 1, "workout_exercises": [ { "exercise_ref": "arm-circles", "exercise_content_version": "v1", "order": 1, "sets": 1, "rest_before_seconds": 0, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "supersets": [ { "order": 1, "workout_exercises": [ { "exercise_ref": "scapular-pull-up", "exercise_content_version": "v7", "order": 1, "sets": 3, "rest_before_seconds": 60, "prescription": { "type": "count", "repetitions": 8 } }, { "exercise_ref": "dead-hang", "exercise_content_version": "v2", "order": 2, "sets": 2, "rest_before_seconds": 45, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "cooldown_supersets": [] } } }, "missing": { "value": { "status": "missing", "workout": null } }, "inactive": { "value": { "status": "inactive", "workout": null } }, "changed": { "value": { "status": "changed", "workout": null } } } } } } }, "operationId": "resolveWorkout", "tags": [ "Content" ] } }, "/ai-coach-connector/v1/actions/preferences/update": { "post": { "summary": "Update one Subject preference", "description": "Bind the Idempotency-Key durably to the exact request; a retry with the same key must return the original result without applying the change twice. Report a business refusal as succeeded false in a 200 response. Kinellect records the update as confirmed only when succeeded is true and receipt_ref is not null; succeeded true with receipt_ref null is recorded as unconfirmed.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "subject_ref", "preference_name", "value", "evidence_turn_ref", "input_fingerprint" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" }, "preference_name": { "enum": [ "preferred_session_length", "training_days", "equipment_preference", "coaching_tone" ] }, "value": { "type": "string", "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 500 }, "evidence_turn_ref": { "type": "string", "format": "uuid", "description": "Conversation Turn whose user text requested the change." }, "input_fingerprint": { "type": "string", "minLength": 64, "maxLength": 64, "description": "Lowercase hexadecimal SHA-256 digest of the proposed update." } } }, "example": { "subject_ref": "7c1f2a4e-2b8d-4f3a-9a51-0d6e4b3c2a10", "preference_name": "preferred_session_length", "value": "30 minutes", "evidence_turn_ref": "5b0f9c7e-0a3c-4d8e-8f21-6a1b2c3d4e5f", "input_fingerprint": "9f2c1e7a4b8d3f6e0a5c2b9d8e7f6a5b4c3d2e1f0a9b8c7d6e5f4a3b2c1d0e9f" } } } }, "responses": { "200": { "description": "Update receipt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PreferenceUpdateReceipt" }, "examples": { "applied": { "value": { "succeeded": true, "receipt_ref": "preference-receipt-8812", "content_version": "profile-2026-09-25", "safe_code": null } }, "refused": { "value": { "succeeded": false, "receipt_ref": null, "content_version": null, "safe_code": "value_not_supported" } } } } } } }, "operationId": "updatePreference", "tags": [ "Actions" ] } }, "/ai-coach-connector/v1/actions/workouts/accept": { "post": { "summary": "Accept the immutable workout command", "description": "Requires the selected action capability workout.save or workout.save_and_schedule independently. Bind the idempotency key and action_ref durably to the exact command. Same-key same-command replay returns the original stable result; changed-command reuse returns command_conflict and never overwrites the original. Save of an existing workout confirms its reference without a copy. Save and schedule is atomic: schedule_conflict creates neither a workout nor a schedule and leaves any existing workout untouched. Return confirmed, conflict or rejected in a successful HTTP 200 response. Transport errors, timeout, malformed/schema-invalid JSON or mismatched identity yield no result; retry retains the immutable command, action identity and key. Eventual public exhaustion after possible dispatch is failed/connector_unconfirmed, never a connector status or assurance of no remote change.", "security": [ { "connectorBearer": [] } ], "parameters": [ { "$ref": "#/components/parameters/TenantHeader" }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutAcceptanceCommand" }, "examples": { "standalone_generated_save": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "standalone_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save", "schedule": null, "approval": "explicit_user_approval", "generated_workout": { "title": "Strength", "warmup_supersets": [ { "order": 1, "rest_between_cycles_seconds": 0, "workout_exercises": [ { "exercise_ref": "warmup", "exercise_content_version": "v1", "order": 1, "sets": 1, "rest_before_seconds": 0, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "supersets": [ { "order": 1, "rest_between_cycles_seconds": 45, "workout_exercises": [ { "exercise_ref": "exercise", "exercise_content_version": "v2", "order": 1, "sets": 3, "rest_before_seconds": 10, "prescription": { "type": "count", "repetitions": 12 } } ] } ], "cooldown_supersets": [] }, "existing_workout_ref": null, "workout_catalog_version": null, "exercise_catalog_version": "exercises-v1", "existing_verified_at": null, "command_fingerprint": "d88d7650ad4fd157230bd5ab10d2c3c995e863a6232cf79042aa9acadb8edd2f" } }, "standalone_generated_save_and_schedule": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "standalone_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save_and_schedule", "schedule": { "local_date": "2026-09-10", "time_zone": "Europe/Oslo" }, "approval": "explicit_user_approval", "generated_workout": { "title": "Strength", "warmup_supersets": [ { "order": 1, "rest_between_cycles_seconds": 0, "workout_exercises": [ { "exercise_ref": "warmup", "exercise_content_version": "v1", "order": 1, "sets": 1, "rest_before_seconds": 0, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "supersets": [ { "order": 1, "rest_between_cycles_seconds": 45, "workout_exercises": [ { "exercise_ref": "exercise", "exercise_content_version": "v2", "order": 1, "sets": 3, "rest_before_seconds": 10, "prescription": { "type": "count", "repetitions": 12 } } ] } ], "cooldown_supersets": [] }, "existing_workout_ref": null, "workout_catalog_version": null, "exercise_catalog_version": "exercises-v1", "existing_verified_at": null, "command_fingerprint": "f313c47fd8d0ba032a0d23bb0dafa64767350b496f6b0ac0c4b036324e379e16" } }, "daily_generated_save": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "daily_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save", "schedule": null, "approval": "explicit_user_approval", "generated_workout": { "title": "Strength", "warmup_supersets": [ { "order": 1, "rest_between_cycles_seconds": 0, "workout_exercises": [ { "exercise_ref": "warmup", "exercise_content_version": "v1", "order": 1, "sets": 1, "rest_before_seconds": 0, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "supersets": [ { "order": 1, "rest_between_cycles_seconds": 45, "workout_exercises": [ { "exercise_ref": "exercise", "exercise_content_version": "v2", "order": 1, "sets": 3, "rest_before_seconds": 10, "prescription": { "type": "count", "repetitions": 12 } } ] } ], "cooldown_supersets": [] }, "existing_workout_ref": null, "workout_catalog_version": null, "exercise_catalog_version": "exercises-v1", "existing_verified_at": null, "command_fingerprint": "45b7ce873c716a95d6be94cdee11a7b837805bb3e9ae7cada4d9c57a44c4ea5f" } }, "daily_generated_save_and_schedule": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "daily_generated", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save_and_schedule", "schedule": { "local_date": "2026-09-10", "time_zone": "Europe/Oslo" }, "approval": "explicit_user_approval", "generated_workout": { "title": "Strength", "warmup_supersets": [ { "order": 1, "rest_between_cycles_seconds": 0, "workout_exercises": [ { "exercise_ref": "warmup", "exercise_content_version": "v1", "order": 1, "sets": 1, "rest_before_seconds": 0, "prescription": { "type": "time", "duration_seconds": 30 } } ] } ], "supersets": [ { "order": 1, "rest_between_cycles_seconds": 45, "workout_exercises": [ { "exercise_ref": "exercise", "exercise_content_version": "v2", "order": 1, "sets": 3, "rest_before_seconds": 10, "prescription": { "type": "count", "repetitions": 12 } } ] } ], "cooldown_supersets": [] }, "existing_workout_ref": null, "workout_catalog_version": null, "exercise_catalog_version": "exercises-v1", "existing_verified_at": null, "command_fingerprint": "542554c884a3cd80283f5d388a36f72b8d873b7abfb900c8c8761d838530fa98" } }, "daily_existing_save": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "daily_existing", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save", "schedule": null, "approval": "explicit_user_approval", "generated_workout": null, "existing_workout_ref": "client-workout-1", "workout_catalog_version": "workouts-v1", "exercise_catalog_version": "exercises-v1", "existing_verified_at": "2026-09-09T12:00:00.000000+00:00", "command_fingerprint": "dd951c01234e246e289303d74f80c29465a71cfcff264a4670fcd06bd4d3aad1" } }, "daily_existing_save_and_schedule": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "subject_ref": "opaque-subject", "source": { "source_kind": "daily_existing", "source_operation_ref": "22222222-2222-4222-8222-222222222222", "source_ref": "33333333-3333-4333-8333-333333333333" }, "configuration_ref": "44444444-4444-4444-8444-444444444444", "configuration_version": 2, "context_ref": "55555555-5555-4555-8555-555555555555", "context_version": 3, "source_content_fingerprint": "5c9c784359cfb0585ad3b4708aef518720b26a516a71d59337f21ff488584346", "action": "save_and_schedule", "schedule": { "local_date": "2026-09-10", "time_zone": "Europe/Oslo" }, "approval": "explicit_user_approval", "generated_workout": null, "existing_workout_ref": "client-workout-1", "workout_catalog_version": "workouts-v1", "exercise_catalog_version": "exercises-v1", "existing_verified_at": "2026-09-09T12:00:00.000000+00:00", "command_fingerprint": "4d3d1f6033c78e21f4c41aa7c8cf504c1c942d869c375fe8a85510c85bed20b3" } } } } } }, "responses": { "200": { "description": "Confirmed, conflict or rejected business result matching the saved command identity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkoutAcceptanceResult" }, "examples": { "confirmed_save": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "command_fingerprint": "d88d7650ad4fd157230bd5ab10d2c3c995e863a6232cf79042aa9acadb8edd2f", "status": "confirmed", "receipt_ref": "receipt-1", "workout_ref": "workout-1", "workout_content_version": "v1", "confirmed_at": "2026-09-09T12:00:00.000000+00:00" } }, "confirmed_scheduled": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "command_fingerprint": "f313c47fd8d0ba032a0d23bb0dafa64767350b496f6b0ac0c4b036324e379e16", "status": "confirmed", "receipt_ref": "receipt-1", "workout_ref": "workout-1", "workout_content_version": "v1", "confirmed_at": "2026-09-09T12:00:00.000000+00:00", "schedule_ref": "schedule-1", "schedule_content_version": "v2" } }, "conflict": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "command_fingerprint": "f313c47fd8d0ba032a0d23bb0dafa64767350b496f6b0ac0c4b036324e379e16", "status": "conflict", "safe_code": "schedule_conflict" } }, "rejected": { "value": { "contract_version": 1, "action_ref": "11111111-1111-4111-8111-111111111111", "command_fingerprint": "f313c47fd8d0ba032a0d23bb0dafa64767350b496f6b0ac0c4b036324e379e16", "status": "rejected", "safe_code": "action_rejected" } } } } } } }, "tags": [ "Actions" ], "operationId": "acceptWorkout" } } }, "components": { "securitySchemes": { "connectorBearer": { "type": "http", "scheme": "bearer", "description": "The connector secret you shared with Kinellect during onboarding." } }, "parameters": { "TenantHeader": { "name": "X-Kinellect-Tenant", "in": "header", "required": true, "schema": { "type": "string", "format": "uuid" } }, "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } }, "schemas": { "SubjectRef": { "type": "string", "format": "uuid", "description": "Kinellect Subject reference, the same value as subject_ref in the public API." }, "SubjectRequest": { "type": "object", "additionalProperties": false, "required": [ "subject_ref" ], "properties": { "subject_ref": { "$ref": "#/components/schemas/SubjectRef" } } }, "ConnectorCapabilities": { "type": "object", "additionalProperties": false, "required": [ "contract_version", "content_version", "capabilities" ], "properties": { "contract_version": { "const": 1, "description": "Must equal the registered connector contract version." }, "content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "capabilities": { "type": "array", "maxItems": 20, "items": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 } } } }, "SubjectContextUnavailable": { "type": "object", "additionalProperties": false, "required": [ "available" ], "properties": { "available": { "const": false } } }, "ResolvedSubjectContext": { "type": "object", "additionalProperties": false, "description": "effective_at must be earlier than valid_through, and both must use a UTC offset (Z or +00:00). When daily_context is present, available_days must hold lowercase English weekday names and the daily_context calendar rules apply.", "required": [ "context_version", "content_version", "provenance", "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", "blocker" ], "properties": { "context_version": { "type": "integer", "minimum": 1 }, "content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "provenance": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 }, "effective_at": { "type": "string", "format": "date-time", "maxLength": 40, "x-max-utf8-bytes": 40 }, "valid_through": { "type": "string", "format": "date-time", "maxLength": 40, "x-max-utf8-bytes": 40 }, "time_zone": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100, "description": "IANA time zone identifier." }, "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": { "type": "string", "minLength": 1, "maxLength": 32, "x-max-utf8-bytes": 32 } }, "unit_system": { "type": "string", "minLength": 1, "maxLength": 20, "x-max-utf8-bytes": 20 }, "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 } }, "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" ], "minLength": 1, "maxLength": 1000, "x-max-utf8-bytes": 1000 }, "daily_context": { "oneOf": [ { "$ref": "#/components/schemas/DailyContext" }, { "type": "null" } ] }, "exercise_constraints": { "type": "array", "maxItems": 30, "description": "constraint_ref values and targets are unique within the list.", "items": { "$ref": "#/components/schemas/ExerciseConstraint" } } } }, "ExerciseCatalogResult": { "type": "object", "additionalProperties": false, "required": [ "content_version", "exercises" ], "properties": { "content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "exercises": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ExerciseProjection" } } } }, "ExerciseProjection": { "type": "object", "additionalProperties": false, "description": "verification_facts and relationships are optional keys.", "required": [ "exercise_ref", "display_name", "movement_pattern", "equipment_refs" ], "properties": { "exercise_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "display_name": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "movement_pattern": { "type": "string", "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 }, "equipment_refs": { "type": "array", "maxItems": 30, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "verification_facts": { "$ref": "#/components/schemas/ExerciseVerificationFacts" }, "relationships": { "$ref": "#/components/schemas/ExerciseRelationships" } } }, "ExerciseVerificationFacts": { "type": "object", "additionalProperties": false, "description": "generation_facts is an optional key.", "required": [ "item_content_version", "active", "available", "prescription_types", "safety_identifiers" ], "properties": { "item_content_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "active": { "type": "boolean" }, "available": { "type": "boolean" }, "prescription_types": { "type": "array", "minItems": 1, "maxItems": 2, "uniqueItems": true, "items": { "enum": [ "count", "time" ] } }, "safety_identifiers": { "type": "array", "maxItems": 30, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "generation_facts": { "$ref": "#/components/schemas/ExerciseGenerationFacts" } } }, "ExerciseGenerationFacts": { "type": "object", "additionalProperties": false, "description": "A count or duration range is either entirely null or complete with minimum <= maximum. count_duration_seconds_per_repetition requires a count range.", "required": [ "minimum_count", "maximum_count", "count_duration_seconds_per_repetition", "minimum_duration_seconds", "maximum_duration_seconds" ], "properties": { "minimum_count": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "maximum_count": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000 }, "count_duration_seconds_per_repetition": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 600 }, "minimum_duration_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 7200 }, "maximum_duration_seconds": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 7200 } } }, "ExerciseRelationships": { "type": "object", "additionalProperties": false, "description": "A reference appears in at most one list and never names the owning exercise.", "required": [ "progression_refs", "regression_refs", "related_refs" ], "properties": { "progression_refs": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "regression_refs": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "related_refs": { "type": "array", "maxItems": 20, "uniqueItems": true, "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } } } }, "WorkoutSearchPage": { "type": "object", "additionalProperties": false, "required": [ "catalog_version", "workout_refs", "next_cursor" ], "properties": { "catalog_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "workout_refs": { "type": "array", "maxItems": 20, "uniqueItems": true, "description": "At most the requested limit.", "items": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 } }, "next_cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 500, "x-max-utf8-bytes": 500 } } }, "WorkoutResolution": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "status", "workout" ], "properties": { "status": { "const": "resolved" }, "workout": { "$ref": "#/components/schemas/ResolvedWorkout" } } }, { "type": "object", "additionalProperties": false, "required": [ "status", "workout" ], "properties": { "status": { "enum": [ "missing", "inactive", "changed" ] }, "workout": { "type": "null" } } } ] }, "ResolvedWorkout": { "type": "object", "additionalProperties": false, "description": "warmup_supersets and cooldown_supersets are optional keys. The three sections hold at most 20 supersets together; superset order starts at 1 and is contiguous within each section. The whole workout holds at most 20 exercises, and each exercise_ref appears once.", "required": [ "workout_ref", "catalog_version", "supersets" ], "properties": { "workout_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "catalog_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "warmup_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ResolvedWorkoutSuperset" } }, "supersets": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/ResolvedWorkoutSuperset" } }, "cooldown_supersets": { "type": "array", "maxItems": 20, "items": { "$ref": "#/components/schemas/ResolvedWorkoutSuperset" } } } }, "ResolvedWorkoutSuperset": { "type": "object", "additionalProperties": false, "description": "Exercise order starts at 1 and is contiguous within the superset.", "required": [ "order", "workout_exercises" ], "properties": { "order": { "type": "integer", "minimum": 1, "maximum": 20 }, "workout_exercises": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/ResolvedWorkoutExercise" } } } }, "ResolvedWorkoutExercise": { "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 } } }, "PreferenceUpdateReceipt": { "type": "object", "additionalProperties": false, "required": [ "succeeded", "receipt_ref", "content_version", "safe_code" ], "properties": { "succeeded": { "type": "boolean" }, "receipt_ref": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "content_version": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200 }, "safe_code": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 100, "x-max-utf8-bytes": 100 } } }, "WorkoutAcceptanceCommand": { "type": "object", "additionalProperties": false, "required": [ "contract_version", "action_ref", "subject_ref", "source", "configuration_ref", "configuration_version", "context_ref", "context_version", "source_content_fingerprint", "action", "schedule", "approval", "generated_workout", "existing_workout_ref", "workout_catalog_version", "exercise_catalog_version", "existing_verified_at", "command_fingerprint" ], "properties": { "contract_version": { "const": 1 }, "action_ref": { "type": "string", "format": "uuid" }, "subject_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "source": { "type": "object", "additionalProperties": false, "required": [ "source_kind", "source_operation_ref", "source_ref" ], "properties": { "source_kind": { "enum": [ "standalone_generated", "daily_generated", "daily_existing" ] }, "source_operation_ref": { "type": "string", "format": "uuid" }, "source_ref": { "type": "string", "format": "uuid" } } }, "configuration_ref": { "type": "string", "format": "uuid" }, "configuration_version": { "type": "integer", "minimum": 1 }, "context_ref": { "type": "string", "format": "uuid" }, "context_version": { "type": "integer", "minimum": 1 }, "source_content_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "action": { "enum": [ "save", "save_and_schedule" ] }, "schedule": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "local_date", "time_zone" ], "properties": { "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." } } }, { "type": "null" } ] }, "approval": { "enum": [ "explicit_user_approval", null ] }, "generated_workout": { "oneOf": [ { "$ref": "#/components/schemas/WorkoutDraft" }, { "type": "null" } ] }, "existing_workout_ref": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "workout_catalog_version": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, { "type": "null" } ] }, "exercise_catalog_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "existing_verified_at": { "oneOf": [ { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." }, { "type": "null" } ] }, "command_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" } }, "allOf": [ { "oneOf": [ { "properties": { "action": { "const": "save" }, "schedule": { "type": "null" } } }, { "properties": { "action": { "const": "save_and_schedule" }, "schedule": { "type": "object", "additionalProperties": false, "required": [ "local_date", "time_zone" ], "properties": { "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." } } } } } ] }, { "oneOf": [ { "properties": { "source": { "properties": { "source_kind": { "enum": [ "standalone_generated", "daily_generated" ] } } }, "generated_workout": { "$ref": "#/components/schemas/WorkoutDraft" }, "existing_workout_ref": { "type": "null" }, "workout_catalog_version": { "type": "null" }, "existing_verified_at": { "type": "null" } } }, { "properties": { "source": { "properties": { "source_kind": { "const": "daily_existing" } } }, "generated_workout": { "type": "null" }, "existing_workout_ref": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "workout_catalog_version": { "type": "string", "minLength": 1, "maxLength": 200, "x-max-utf8-bytes": 200, "pattern": "^[^\\u0000]*$" }, "existing_verified_at": { "type": "string", "format": "date-time", "pattern": "(Z|\\+00:00)$", "description": "UTC timestamp." } } } ] } ], "description": "Exact immutable saved command. Source identity, configuration/context references and versions, verified content and approval are fingerprint-bound. Generated sources preserve the saved draft hierarchy with contiguous section-local ordering and at most 20 exercises total, without duplicate exercise references. Existing sources name the verified client workout and catalog versions and do not copy it. command_fingerprint is SHA-256 of the canonical UTF-8 JSON in the property order shown, excluding command_fingerprint, with no whitespace or escaped slashes/Unicode. Decoder requires these canonical command bytes; replay never rebuilds or replaces them." }, "WorkoutAcceptanceResult": { "description": "Exactly three matching response identity fields bind the saved command. No Subject, source, action, schedule or approval echo is allowed. Only confirmed includes real receipts and successful effects. Select the confirmed field set from the saved command action: save omits schedule references; save_and_schedule requires both. Existing-workout confirmation must retain its original workout reference. All three business outcomes complete the generic Operation.", "oneOf": [ { "type": "object", "additionalProperties": false, "required": [ "contract_version", "action_ref", "command_fingerprint", "status", "receipt_ref", "workout_ref", "workout_content_version", "confirmed_at" ], "properties": { "contract_version": { "const": 1 }, "action_ref": { "type": "string", "format": "uuid" }, "command_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "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": [ "contract_version", "action_ref", "command_fingerprint", "status", "receipt_ref", "workout_ref", "workout_content_version", "confirmed_at", "schedule_ref", "schedule_content_version" ], "properties": { "contract_version": { "const": 1 }, "action_ref": { "type": "string", "format": "uuid" }, "command_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "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": [ "contract_version", "action_ref", "command_fingerprint", "status", "safe_code" ], "properties": { "contract_version": { "const": 1 }, "action_ref": { "type": "string", "format": "uuid" }, "command_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "status": { "const": "conflict" }, "safe_code": { "enum": [ "schedule_conflict", "command_conflict" ] } } }, { "type": "object", "additionalProperties": false, "required": [ "contract_version", "action_ref", "command_fingerprint", "status", "safe_code" ], "properties": { "contract_version": { "const": 1 }, "action_ref": { "type": "string", "format": "uuid" }, "command_fingerprint": { "type": "string", "pattern": "^[0-9a-f]{64}$" }, "status": { "const": "rejected" }, "safe_code": { "const": "action_rejected" } } } ] }, "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" } ] } } }, "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." }, "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" ] } } } } }, "servers": [ { "url": "https://{connector_host}", "description": "Your connector base URL, registered with Kinellect during onboarding.", "variables": { "connector_host": { "default": "connector.example.com", "description": "Host (and optional path prefix) of your HTTPS connector." } } } ], "security": [ { "connectorBearer": [] } ], "tags": [ { "name": "Discovery", "description": "Capability discovery performed when a client configuration is activated." }, { "name": "Context", "description": "Authoritative, current facts about one user." }, { "name": "Content", "description": "Your exercise and workout catalog." }, { "name": "Actions", "description": "Changes Kinellect asks you to make on the user's behalf." } ] }