openapi: 3.1.0
info:
  title: Kairos HTTP API
  version: 1.0.0
  license:
    name: Apache-2.0
    identifier: Apache-2.0
  description: |
    Exact contract for the current `/api/v1` HTTP surface. JSON names use
    snake_case. Collection fields are always arrays, including when empty;
    optional single values are encoded as null.
servers:
  - url: http://127.0.0.1:8080
security:
  - bearerAuth: []
  - trustedActorId: []
paths:
  /healthz:
    get:
      operationId: health
      summary: Health
      security: []
      responses:
        '200':
          description: Healthy
          content:
            application/json:
              schema:
                type: object
                required: [status]
                properties:
                  status: { const: ok }
  /api/v1/auth/config:
    get:
      operationId: getAuthenticationConfig
      summary: Get Authentication Config
      security: []
      responses:
        '200':
          description: Authentication mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticationConfigResponse'
  /api/v1/session:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getSession
      summary: Get Session
      description: The deployment Admin Token resolves to a stable database-bound Human with an empty role, using ordinary Human business permissions. Its optional display_name is system admin; the actor ID remains unchanged.
      responses:
        '200': { $ref: '#/components/responses/Session' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/identities:
    get:
      operationId: listIdentities
      summary: List Identities
      description: Requires the administrator bearer token. Available only when identity management is configured.
      security: [{ bearerAuth: [] }]
      responses:
        '200':
          description: Identities
          content:
            application/json:
              schema: { $ref: '#/components/schemas/IdentityListResponse' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    post:
      operationId: createIdentity
      summary: Create Identity
      description: Requires the deployment administrator bearer token, not an issued Identity Token. Atomically creates an identity and issues its initial token, returned only once. A lost response cannot retrieve that token again; do not blindly retry.
      security: [{ bearerAuth: [] }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateIdentityRequest' }
      responses:
        '201': { $ref: '#/components/responses/IssuedToken' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/identities/{kind}/{actor_id}:
    parameters:
      - $ref: '#/components/parameters/ActorKindPath'
      - $ref: '#/components/parameters/ActorIdPath'
    get:
      operationId: getIdentity
      summary: Get Identity
      security: [{ bearerAuth: [] }]
      responses:
        '200': { $ref: '#/components/responses/Identity' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/identities/{kind}/{actor_id}/token:
    parameters:
      - $ref: '#/components/parameters/ActorKindPath'
      - $ref: '#/components/parameters/ActorIdPath'
    post:
      operationId: rotateIdentityToken
      summary: Rotate Identity Token
      description: Deployment-managed Admin Humans return 403; change deployment configuration and restart all instances instead.
      security: [{ bearerAuth: [] }]
      responses:
        '200': { $ref: '#/components/responses/IssuedToken' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    delete:
      operationId: revokeIdentityToken
      summary: Revoke Identity Token
      description: Deployment-managed Admin Humans return 403; change deployment configuration and restart all instances instead.
      security: [{ bearerAuth: [] }]
      responses:
        '204': { description: Token revoked }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/workflows:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listWorkflowDefinitions
      summary: List Workflow Definition Catalog
      description: Returns the maximum stored version for each Definition ID.
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Workflow Definition catalog entries
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowDefinitionListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/workflows/{definition_id}:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getLatestWorkflowDefinition
      summary: Get Latest Stored Workflow Definition
      responses:
        '200': { $ref: '#/components/responses/WorkflowDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/workflows/{definition_id}/versions:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listWorkflowDefinitionVersions
      summary: List Workflow Definition Versions
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Workflow Definition versions, newest first
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkflowDefinitionListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    post:
      operationId: createWorkflowDefinitionVersion
      summary: Append Workflow Definition Version
      description: Workflow Definitions are immutable and append-only. Omit `base_version` to create version 1 for a new ID. For an existing ID, `base_version` must equal the latest stored version; the server atomically assigns the next version or returns `409` if another edit was accepted first.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateWorkflowDefinitionRequest' }
      responses:
        '201': { $ref: '#/components/responses/WorkflowDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/workflows/{definition_id}/versions/{version}:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/VersionPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getWorkflowDefinition
      summary: Get Workflow Definition
      responses:
        '200': { $ref: '#/components/responses/WorkflowDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/blackboards:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listBlackboardDefinitions
      summary: List Blackboard Definition Catalog
      description: Returns the maximum stored version for each Definition ID.
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Blackboard Definition catalog entries
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BlackboardDefinitionListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/blackboards/{definition_id}:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getLatestBlackboardDefinition
      summary: Get Latest Stored Blackboard Definition
      responses:
        '200': { $ref: '#/components/responses/BlackboardDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/blackboards/{definition_id}/versions:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listBlackboardDefinitionVersions
      summary: List Blackboard Definition Versions
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Blackboard Definition versions, newest first
          content:
            application/json:
              schema: { $ref: '#/components/schemas/BlackboardDefinitionListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    post:
      operationId: createBlackboardDefinitionVersion
      summary: Append Blackboard Definition Version
      description: Blackboard Definitions are immutable and append-only. Omit `base_version` to create version 1 for a new ID. For an existing ID, `base_version` must equal the latest stored version; the server atomically assigns the next version or returns `409` if another edit was accepted first.
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateDefinitionRequest' }
      responses:
        '201': { $ref: '#/components/responses/BlackboardDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/definitions/blackboards/{definition_id}/versions/{version}:
    parameters:
      - $ref: '#/components/parameters/DefinitionIdPath'
      - $ref: '#/components/parameters/VersionPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getBlackboardDefinition
      summary: Get Blackboard Definition
      responses:
        '200': { $ref: '#/components/responses/BlackboardDefinition' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: findWork
      summary: Find Work
      parameters:
        - $ref: '#/components/parameters/TagQuery'
        - name: limit
          in: query
          schema: { type: integer, minimum: 0, maximum: 50, default: 5 }
          description: Maximum candidates returned for each candidate kind. Omission or zero uses 5.
      responses:
        '200':
          description: Work candidates
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkCandidateListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/human-attention:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listHumanAttention
      summary: List Human Attention
      description: Returns pending Reviews, unclaimed Pending Human Tasks, Working Tasks actively claimed by the requesting Human (including executor=either), and WorkItems awaiting human acceptance. Human callers also receive one workflow_recovery entry per Failed Workflow or Open Workflow with a current unreplaced Failed Task. Recovery entries exclude WorkItems already used as a start-over source; their optional Task is the most recently updated unreplaced Failed Task (ties use ascending Task ID), not a Task execution action. Open the WorkItem to recover it. Recovery ends when no current failures remain or a start-over replacement exists. Other actors' Working Tasks and unclaimed either Tasks are excluded. Eligibility and recovery grouping precede pagination. Reviews retain priority; remaining items sort by the attached Task's updated_at, or the WorkItem's updated_at when task is null, descending, then WorkItem ID and Task ID ascending. human_task entries have task.status pending or working. Non-open WorkItems contribute only acceptance or recovery entries.
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Items requiring human attention
          content:
            application/json:
              schema: { $ref: '#/components/schemas/HumanAttentionListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/daemon-instances:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listDaemonInstances
      summary: List Daemon instances (Human only)
      description: Default scope is instances with a report in the last 30 days. Connectivity is computed from Core receive time; reporting means a report arrived within 45 seconds.
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
        - name: agent_id
          in: query
          schema: { type: string }
        - name: include_history
          in: query
          schema: { type: boolean, default: false }
      responses:
        '200': { description: Daemon instances, content: { application/json: { schema: { $ref: '#/components/schemas/DaemonInstanceListResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    post:
      operationId: registerDaemonInstance
      summary: Register a process instance (Agent only)
      description: Same ID, actor, and immutable configuration is idempotent and returns 200 without refreshing last_report_at.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/DaemonRegistration' } } }
      responses:
        '201': { description: Registered, content: { application/json: { schema: { $ref: '#/components/schemas/DaemonInstanceResponse' } } } }
        '200': { description: Matching registration replay, content: { application/json: { schema: { $ref: '#/components/schemas/DaemonInstanceResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/daemon-instances/{instance_id}:
    parameters:
      - name: instance_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getDaemonInstance
      summary: Get a Daemon instance (Human only)
      responses:
        '200': { description: Instance snapshot, content: { application/json: { schema: { $ref: '#/components/schemas/DaemonInstanceResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/daemon-instances/{instance_id}/reports:
    parameters:
      - name: instance_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: reportDaemonInstance
      summary: Send snapshot and events (owning Agent only)
      description: Body limit 64 KiB. Events are deduplicated by sequence; only a newer revision replaces the snapshot and refreshes last_report_at. A successful response accepts the entire submitted batch.
      requestBody:
        required: true
        content: { application/json: { schema: { $ref: '#/components/schemas/DaemonReport' } } }
      responses:
        '204': { description: Report accepted }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/daemon-instances/{instance_id}/events:
    parameters:
      - name: instance_id
        in: path
        required: true
        schema: { type: string, format: uuid }
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listDaemonEvents
      summary: List Daemon events (Human only)
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200': { description: Events in descending sequence, content: { application/json: { schema: { $ref: '#/components/schemas/DaemonEventListResponse' } } } }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items:
    parameters:
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listWorkItems
      summary: List Work Items
      parameters:
        - name: status
          in: query
          description: Repeat to match any listed status.
          schema: { type: array, items: { $ref: '#/components/schemas/WorkItemStatus' } }
          style: form
          explode: true
        - name: mode
          in: query
          description: Repeat to match any listed mode.
          schema: { type: array, items: { $ref: '#/components/schemas/CoordinationMode' } }
          style: form
          explode: true
        - $ref: '#/components/parameters/TagQuery'
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: WorkItems, newest first
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkItemListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '500': { $ref: '#/components/responses/InternalServerError' }
    post:
      operationId: createWorkItem
      summary: Create Work Item
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateWorkItemRequest' }
      responses:
        '201': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/context:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getWorkItemContext
      summary: Get Work Item Context
      description: Read durable context across all WorkItem lifecycle states, subject to authorization. Failed Workflow WorkItems remain readable and may be recovered by a Human through Continue or Start over.
      responses:
        '200':
          description: Durable WorkItem execution context
          content:
            application/json:
              schema: { $ref: '#/components/schemas/WorkItemContextResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/artifacts:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: listArtifacts
      summary: List Artifacts
      parameters:
        - $ref: '#/components/parameters/PageLimitQuery'
        - $ref: '#/components/parameters/PageCursorQuery'
      responses:
        '200':
          description: Submitted Artifacts
          content:
            application/json:
              schema: { $ref: '#/components/schemas/ArtifactListResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/coordination-claims:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: claimWorkCandidate
      summary: Claim Work Candidate
      description: Agent-only reservation for an empty Blackboard, Blackboard completion decision, or Agent acceptance decision.
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CoordinationClaimRequest' }
      responses:
        '201': { $ref: '#/components/responses/CoordinationClaim' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/coordination-claims/{claim_id}:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/ClaimIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    delete:
      operationId: releaseCoordinationClaim
      summary: Release Coordination Claim
      responses:
        '204': { description: Coordination Claim released }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/coordination-claims/{claim_id}/heartbeat:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/ClaimIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: heartbeatCoordinationClaim
      summary: Heartbeat Coordination Claim
      requestBody:
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LeaseRequest' }
      responses:
        '200': { $ref: '#/components/responses/CoordinationClaim' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/tasks:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: createBlackboardTask
      summary: Create Blackboard Task
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaskDraftRequest' }
      responses:
        '201': { $ref: '#/components/responses/Task' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/relations:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: addBlackboardRelation
      summary: Add Blackboard Relation
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/AddRelationRequest' }
      responses:
        '201': { $ref: '#/components/responses/TaskRelation' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/completion:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: submitBlackboardCompletion
      summary: Submit Blackboard Completion
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [result]
              properties:
                coordination_claim_id: { type: string, description: Required for Agent callers. }
                result: { $ref: '#/components/schemas/HistoryText' }
      responses:
        '200': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/acceptance:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: acceptBlackboardCompletion
      summary: Accept Blackboard Completion
      requestBody:
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties:
                coordination_claim_id: { type: string, description: Required for Agent acceptance; omitted for Human acceptance. }
      responses:
        '200': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/continue:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: continueWorkflow
      summary: Continue a Workflow with current failures
      description: Human-only unified Continue execution for a Failed Workflow with unfinished work or an Open Workflow with current failed Tasks. Atomically creates replacements for all current failed attempts and attempts revoked by whole-workflow failure, preserves running/successful branches, normal Pending attempts and pending reviews, and replays missing decision inputs. A Task that exhausted its Claim history capacity also requires replacement. No arbitrary Task selection or separate retry endpoint. Retains the binding and per-node counts. The optional limit cannot decrease the effective limit and must leave room for all required retries. Ended Claims remain invalid. Stale versions, ineligible state or insufficient capacity return 409 and roll back all changes. No Agent MCP mutation.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [version]
              properties:
                version: { type: integer, format: int64, minimum: 0 }
                max_task_instances_per_node: { type: integer, minimum: 0, maximum: 500, default: 0, description: Zero keeps the effective limit. }
                instructions: { $ref: '#/components/schemas/HistoryText' }
      responses:
        '200': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/start-over:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: startOverWorkflow
      summary: Start over in a new WorkItem using the source Workflow and intent
      description: Human-only. Copies original intent, pinned Definition version, current limit override and a bounded failure summary; creates fresh start Tasks with independent counts. An Open source with current failed Tasks is failed and its remaining Claims revoked atomically; an already Failed source stays Failed. The source retains history and advances its version. The UTF-8-safe 32 KiB start-over summary includes the source ID and current WorkItem/failed Task reasons. Only Human instructions supplied in this request are carried separately. Old URLs, Artifacts, Reviews, Submissions, instructions and start-over summaries are not scanned or copied. Scoped executors cannot read the source WorkItem; include external outcomes to reuse in the new instructions. External actions are not undone and managed artifact files are not copied. Identical requests with the same Idempotency-Key return the same new WorkItem. No arbitrary-stage replay or Agent MCP mutation.
      parameters:
        - name: Idempotency-Key
          in: header
          required: true
          schema: { type: string }
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [version]
              properties:
                version: { type: integer, format: int64, minimum: 0 }
                instructions: { $ref: '#/components/schemas/HistoryText' }
      responses:
        '201': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/work-items/{work_item_id}/cancellation:
    parameters:
      - $ref: '#/components/parameters/WorkItemIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: cancelWorkItem
      summary: Cancel Work Item
      description: Human-only terminal cancellation. Active Task and Coordination Claims are ended; no Task is marked failed.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [reason]
              properties: { reason: { $ref: '#/components/schemas/HistoryText', pattern: '.*\S.*' } }
      responses:
        '200': { $ref: '#/components/responses/WorkItem' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getTaskDetail
      summary: Get Task Detail
      responses:
        '200':
          description: Viewer-facing Task detail
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskDetailResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/context:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getTaskContext
      summary: Get Task Context
      responses:
        '200':
          description: Executor-authorized Task context
          content:
            application/json:
              schema: { $ref: '#/components/schemas/TaskContextResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/claims:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: claimTask
      summary: Claim Task
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaskClaimRequest' }
      responses:
        '201': { $ref: '#/components/responses/Claim' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/claims/{claim_id}:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/ClaimIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    delete:
      operationId: releaseClaim
      summary: Release Claim
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              properties: { reason: { $ref: '#/components/schemas/HistoryText' } }
      responses:
        '204': { description: Claim released }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/claims/{claim_id}/heartbeat:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/ClaimIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: heartbeatClaim
      summary: Heartbeat Claim
      requestBody:
        required: false
        content:
          application/json:
            schema: { $ref: '#/components/schemas/LeaseRequest' }
      responses:
        '200': { $ref: '#/components/responses/Claim' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/submissions:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: submitTask
      summary: Submit Task
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/SubmitTaskRequest' }
      responses:
        '201': { $ref: '#/components/responses/Submission' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/artifacts:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: createArtifact
      summary: Create Artifact
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/CreateArtifactRequest' }
      responses:
        '201': { $ref: '#/components/responses/Artifact' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/artifact-uploads:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: uploadArtifact
      summary: Upload Artifact
      parameters:
        - $ref: '#/components/parameters/RequiredIdempotencyKey'
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required: [claim_id, name, file]
              properties:
                claim_id: { type: string }
                name: { type: string }
                file: { type: string, format: binary }
      responses:
        '201': { $ref: '#/components/responses/Artifact' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '413': { $ref: '#/components/responses/PayloadTooLarge' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/artifacts/{artifact_id}/content:
    parameters:
      - $ref: '#/components/parameters/ArtifactIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    get:
      operationId: getArtifactContent
      summary: Get Artifact Content
      responses:
        '200':
          description: Managed Artifact bytes
          headers:
            Content-Disposition:
              schema: { type: string }
          content:
            application/octet-stream:
              schema: { type: string, format: binary }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/failures:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: failTask
      summary: Fail Task
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/FailTaskRequest' }
      responses:
        '201': { $ref: '#/components/responses/Failure' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/skip:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: skipBlackboardTask
      summary: Skip Blackboard Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [reason]
              properties: { reason: { $ref: '#/components/schemas/HistoryText' } }
      responses:
        '200': { $ref: '#/components/responses/Task' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/decomposition:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: decomposeBlackboardTask
      summary: Decompose Blackboard Task
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [claim_id, children]
              properties:
                claim_id: { type: string }
                children:
                  type: array
                  minItems: 1
                  items: { $ref: '#/components/schemas/TaskDraftRequest' }
      responses:
        '201':
          description: Decomposed Task and initial children
          content:
            application/json:
              schema: { $ref: '#/components/schemas/DecompositionResponse' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/children:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: addBlackboardChildTask
      summary: Add Blackboard Child Task
      parameters: [{ $ref: '#/components/parameters/IdempotencyKey' }]
      requestBody:
        required: true
        content:
          application/json:
            schema: { $ref: '#/components/schemas/TaskDraftRequest' }
      responses:
        '201': { $ref: '#/components/responses/Task' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
  /api/v1/tasks/{task_id}/reviews/{review_id}/decision:
    parameters:
      - $ref: '#/components/parameters/TaskIdPath'
      - $ref: '#/components/parameters/ReviewIdPath'
      - $ref: '#/components/parameters/TrustedActorKindHeader'
      - $ref: '#/components/parameters/TrustedActorRoleHeader'
    post:
      operationId: decideReview
      summary: Decide Review
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              required: [decision]
              properties:
                decision: { type: string, enum: [approved, rejected] }
                feedback: { $ref: '#/components/schemas/HistoryText' }
      responses:
        '200': { $ref: '#/components/responses/Review' }
        '400': { $ref: '#/components/responses/BadRequest' }
        '401': { $ref: '#/components/responses/Unauthorized' }
        '403': { $ref: '#/components/responses/Forbidden' }
        '404': { $ref: '#/components/responses/NotFound' }
        '409': { $ref: '#/components/responses/Conflict' }
        '500': { $ref: '#/components/responses/InternalServerError' }
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Identity Token, deployment Admin Token (ordinary Human), or scoped canonical `krs_claim_` Executor Token for business routes; only the deployment Admin Token for identity routes. Admin configuration requires at least 32 visible ASCII characters (0x21–0x7E), no whitespace or control characters, and must not match canonical Executor format or an existing Identity credential.
    trustedActorId:
      type: apiKey
      in: header
      name: X-Kairos-Actor-Id
      description: Required Trusted Mode actor ID. After trimming surrounding whitespace, must be nonblank and must not equal dot (.) or dot-dot (..). The optional Kind and conditionally required Role are operation header parameters.
  parameters:
    TrustedActorKindHeader:
      name: X-Kairos-Actor-Kind
      in: header
      required: false
      description: Trusted Mode actor kind. Defaults to `agent` when omitted.
      schema:
        type: string
        enum: [human, agent]
        default: agent
    TrustedActorRoleHeader:
      name: X-Kairos-Actor-Role
      in: header
      required: false
      description: Trusted Mode role. Required for Agent identities and omitted for Human identities.
      schema: { type: string }
    IdempotencyKey:
      name: Idempotency-Key
      in: header
      required: false
      schema: { type: string, minLength: 1 }
      description: Stable key for replaying an identical resource-creation request after a lost response.
    RequiredIdempotencyKey:
      name: Idempotency-Key
      in: header
      required: true
      schema: { type: string, minLength: 1 }
      description: Stable key used only to recover a managed Artifact upload across file-store and database writes.
    ActorKindPath:
      name: kind
      in: path
      required: true
      schema: { $ref: '#/components/schemas/ActorKind' }
    ActorIdPath:
      name: actor_id
      in: path
      required: true
      schema: { $ref: '#/components/schemas/ActorID' }
    DefinitionIdPath:
      name: definition_id
      in: path
      required: true
      schema: { type: string, pattern: '^[a-z0-9-]+$' }
    VersionPath:
      name: version
      in: path
      required: true
      schema: { type: integer, format: int64, minimum: 1 }
    WorkItemIdPath:
      name: work_item_id
      in: path
      required: true
      schema: { type: string }
    TaskIdPath:
      name: task_id
      in: path
      required: true
      schema: { type: string }
    ClaimIdPath:
      name: claim_id
      in: path
      required: true
      schema: { type: string }
    ArtifactIdPath:
      name: artifact_id
      in: path
      required: true
      schema: { type: string }
    ReviewIdPath:
      name: review_id
      in: path
      required: true
      schema: { type: string }
    TagQuery:
      name: tag
      in: query
      description: Repeat to require all listed tags where tag filtering applies.
      schema: { type: array, items: { type: string } }
      style: form
      explode: true
    PageLimitQuery:
      name: limit
      in: query
      description: Maximum number of collection items to return.
      schema: { type: integer, minimum: 1, maximum: 200, default: 50 }
    PageCursorQuery:
      name: cursor
      in: query
      description: Opaque `next_cursor` from the preceding page of the same collection.
      schema: { type: string, minLength: 1, maxLength: 2048 }
  responses:
    BadRequest:
      description: Invalid request (`invalid_request`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Unauthorized:
      description: Missing or invalid credentials (`unauthenticated`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Forbidden:
      description: The resolved actor may not perform this operation (`forbidden`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    NotFound:
      description: The requested resource does not exist (`not_found`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Conflict:
      description: The operation conflicts with current state or incompatible reuse of a resource-creation key (`conflict`), or the WorkItem was terminally cancelled (`work_item_cancelled`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    PayloadTooLarge:
      description: The managed Artifact upload exceeds the configured limit (`artifact_too_large`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    InternalServerError:
      description: An unexpected server or persistence error occurred (`internal_error`)
      content:
        application/json:
          schema: { $ref: '#/components/schemas/ErrorResponse' }
    Session:
      description: Resolved caller identity
      content: { application/json: { schema: { $ref: '#/components/schemas/SessionResponse' } } }
    Identity:
      description: Identity record
      content: { application/json: { schema: { $ref: '#/components/schemas/IdentityResponse' } } }
    IssuedToken:
      description: Newly issued token, returned only in this response
      content: { application/json: { schema: { $ref: '#/components/schemas/IssuedTokenResponse' } } }
    WorkflowDefinition:
      description: Workflow Definition
      content: { application/json: { schema: { $ref: '#/components/schemas/WorkflowDefinitionResponse' } } }
    BlackboardDefinition:
      description: Blackboard Definition
      content: { application/json: { schema: { $ref: '#/components/schemas/BlackboardDefinitionResponse' } } }
    WorkItem:
      description: WorkItem
      content: { application/json: { schema: { $ref: '#/components/schemas/WorkItemResponse' } } }
    Task:
      description: Task
      content: { application/json: { schema: { $ref: '#/components/schemas/TaskResponse' } } }
    TaskRelation:
      description: Task Relation
      content: { application/json: { schema: { $ref: '#/components/schemas/TaskRelationResponse' } } }
    Claim:
      description: Claim
      content: { application/json: { schema: { $ref: '#/components/schemas/ClaimResponse' } } }
    CoordinationClaim:
      description: WorkItem coordination Claim
      content: { application/json: { schema: { $ref: '#/components/schemas/CoordinationClaimResponse' } } }
    Submission:
      description: Submission
      content: { application/json: { schema: { $ref: '#/components/schemas/SubmissionResponse' } } }
    Artifact:
      description: Artifact
      content: { application/json: { schema: { $ref: '#/components/schemas/ArtifactResponse' } } }
    Failure:
      description: Failure
      content: { application/json: { schema: { $ref: '#/components/schemas/FailureResponse' } } }
    Review:
      description: Review
      content: { application/json: { schema: { $ref: '#/components/schemas/ReviewResponse' } } }
  schemas:
    ActorID:
      type: string
      minLength: 1
      not: { enum: ['.', '..'] }
      description: Must contain a non-whitespace character and must not equal the reserved URL path segments dot (.) or dot-dot (..). Unicode and meaningful surrounding whitespace are preserved. Unique within the actor kind. Trusted transport headers trim surrounding whitespace before validation.
    ActorKind: { type: string, enum: [human, agent] }
    CoordinationMode: { type: string, enum: [workflow, blackboard] }
    WorkItemStatus: { type: string, enum: [open, completed, cancelled, failed, awaiting_agent_acceptance, awaiting_human_acceptance] }
    TaskStatus: { type: string, enum: [pending, working, waiting_children, in_review, completed, skipped, failed] }
    ExecutorRequirement: { type: string, enum: [agent, human, either] }
    DateTime: { type: string, format: date-time }
    NullableDateTime: { type: [string, 'null'], format: date-time }
    NullableString: { type: [string, 'null'] }
    NullableCursor: { type: [string, 'null'], minLength: 1, maxLength: 2048 }
    StringArray: { type: array, items: { type: string } }
    DaemonRegistration:
      type: object
      additionalProperties: false
      required: [id, process_started_at, daemon_version, adapter, slots]
      properties:
        id: { type: string, format: uuid, description: Lowercase random process ID. }
        name: { type: string, description: Optional display name after surrounding whitespace is removed; at most 128 UTF-8 bytes., x-maxBytes: 128 }
        process_started_at: { $ref: '#/components/schemas/DateTime' }
        daemon_version: { type: string, x-maxBytes: 64 }
        adapter: { type: string, x-maxBytes: 32 }
        slots: { type: integer, minimum: 1 }
        tags: { type: array, maxItems: 50, items: { type: string, x-maxBytes: 128 } }
    DaemonDispatch:
      type: object
      additionalProperties: false
      required: [id, candidate_kind, work_item_id, claim_status, state, attempts, started_at]
      properties:
        id: { type: string, format: uuid }
        candidate_kind: { type: string, enum: [task, empty_blackboard, blackboard_completion, work_item_acceptance] }
        work_item_id: { type: string }
        task_id: { $ref: '#/components/schemas/NullableString', description: Required and non-empty for task candidates; null for coordination candidates. }
        claim_id: { $ref: '#/components/schemas/NullableString', description: Required and non-empty for active or ended Claims; null before a Claim is known. }
        claim_status: { type: string, enum: [not_attempted, uncertain, active, ended], description: active and ended require claim_id; not_attempted and uncertain require claim_id to be null. }
        state: { type: string, enum: [prepared, claimed, starting, running, finalizing, stopping, finished, lost] }
        attempts: { type: integer, minimum: 0 }
        started_at: { $ref: '#/components/schemas/DateTime' }
    DaemonEventDetails:
      type: object
      additionalProperties: false
      description: Optional bounded facts for candidate-scoped events. Values use the shared lifecycle enums; process-level events use an empty object.
      properties:
        reason: { type: string, enum: [requested, lease_lost, authority_lost, runtime_failure, protocol_error, core_rejected] }
        state: { type: string, enum: [finished, lost] }
        outcome: { type: string, enum: [completed, decomposed, retryable_failure, work_item_failure, human_intervention_required, candidate_declined, create_task, submit_completion, accept_completion] }
        applied: { type: boolean, description: On dispatch_ended, false means the outcome was not confirmed as applied. }
        attempts: { type: integer, minimum: 0 }
        duration_ms: { type: integer, format: int64, minimum: 0 }
    DaemonEvent:
      type: object
      additionalProperties: false
      description: Daemon-generated candidate events include relevant navigation references. Core validates supplied references as non-empty strings but does not use them as business-state constraints.
      required: [sequence, kind, candidate_kind, occurred_at, dispatch_id, work_item_id, task_id, claim_id, details]
      properties:
        sequence: { type: integer, format: int64, minimum: 1 }
        kind: { type: string, enum: [admission_paused, admission_resumed, claim_acquired, harness_started, harness_retry, outcome_applied, dispatch_ended, candidate_quarantined, shutdown_started, daemon_stopped] }
        candidate_kind:
          oneOf:
            - { type: string, enum: [task, empty_blackboard, blackboard_completion, work_item_acceptance] }
            - { type: 'null' }
          description: Candidate kind when the event concerns a Dispatch.
        occurred_at: { $ref: '#/components/schemas/DateTime' }
        received_at: { type: string, format: date-time, readOnly: true, description: Core receive time; present in read responses. }
        dispatch_id: { $ref: '#/components/schemas/NullableString', description: Dispatch navigation reference when available. }
        work_item_id: { $ref: '#/components/schemas/NullableString', description: WorkItem navigation reference when available. }
        task_id: { $ref: '#/components/schemas/NullableString', description: Task navigation reference when available. }
        claim_id: { $ref: '#/components/schemas/NullableString', description: Claim navigation reference when available. }
        details: { $ref: '#/components/schemas/DaemonEventDetails' }
    DaemonReport:
      type: object
      additionalProperties: false
      required: [revision, lifecycle, health]
      properties:
        revision: { type: integer, format: int64, minimum: 1 }
        lifecycle: { type: string, enum: [running, stopping, stopped], description: Daemon process lifecycle; stopping is reported throughout graceful shutdown before the final stopped report. }
        health: { type: string, enum: [unknown, healthy, paused] }
        active_count: { type: integer, minimum: 0 }
        active_dispatches: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/DaemonDispatch' } }
        omitted_active_count: { type: integer, minimum: 0 }
        dropped_events: { type: integer, minimum: 0 }
        events: { type: array, maxItems: 50, items: { $ref: '#/components/schemas/DaemonEvent' } }
    DaemonInstance:
      type: object
      additionalProperties: false
      required: [id, name, agent_id, process_started_at, registered_at, last_report_at, stopped_at, daemon_version, adapter, slots, tags, last_revision, lifecycle, health, active_count, active_dispatches, omitted_active_count, dropped_events, connectivity, as_of]
      properties:
        id: { type: string, format: uuid }
        name: { type: string }
        agent_id: { type: string }
        process_started_at: { $ref: '#/components/schemas/DateTime' }
        registered_at: { $ref: '#/components/schemas/DateTime' }
        last_report_at: { $ref: '#/components/schemas/DateTime' }
        stopped_at: { $ref: '#/components/schemas/NullableDateTime' }
        daemon_version: { type: string }
        adapter: { type: string }
        slots: { type: integer, minimum: 1 }
        tags: { type: array, items: { type: string } }
        last_revision: { type: integer, format: int64 }
        lifecycle: { type: string, enum: [running, stopping, stopped], description: Last reported Daemon process lifecycle. }
        health: { type: string, enum: [unknown, healthy, paused] }
        active_count: { type: integer }
        active_dispatches: { type: array, items: { $ref: '#/components/schemas/DaemonDispatch' } }
        omitted_active_count: { type: integer }
        dropped_events: { type: integer, minimum: 0 }
        connectivity: { type: string, enum: [reporting, stale, stopped] }
        as_of: { $ref: '#/components/schemas/DateTime' }
    DaemonInstanceResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/DaemonInstance' } }
    DaemonInstanceListResponse:
      type: object
      required: [data, next_cursor, as_of]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/DaemonInstance' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
        as_of: { $ref: '#/components/schemas/DateTime' }
    DaemonEventListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/DaemonEventResponse' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    DaemonEventResponse:
      allOf:
        - $ref: '#/components/schemas/DaemonEvent'
        - type: object
          required: [received_at, dispatch_id, work_item_id, task_id, claim_id, details]
    HistoryText:
      type: string
      description: Text retained in history or copied into the event log; limited to 32 KiB of UTF-8 encoded bytes.
      x-maxBytes: 32768
    ErrorResponse:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code: { type: string }
            message: { type: string }
    AuthenticationConfigResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [mode]
          properties: { mode: { type: string, enum: [trusted, authenticated] } }
    ActorRef:
      type: object
      required: [kind, id]
      properties:
        kind: { $ref: '#/components/schemas/ActorKind' }
        id: { $ref: '#/components/schemas/ActorID' }
    NullableActorRef:
      oneOf:
        - $ref: '#/components/schemas/ActorRef'
        - type: 'null'
    Session:
      type: object
      required: [id, kind, role]
      properties:
        id: { $ref: '#/components/schemas/ActorID' }
        kind: { $ref: '#/components/schemas/ActorKind' }
        role: { type: string }
    Identity:
      allOf:
        - $ref: '#/components/schemas/Session'
        - type: object
          required: [credential_source, token_active, version, created_at, updated_at]
          properties:
            credential_source: { type: string, enum: [identity, admin] }
            token_active:
              type: boolean
              description: Whether an issued Identity Token is active. Always false for the deployment-managed Admin Human.
            version: { type: integer, format: int64 }
            created_at: { $ref: '#/components/schemas/DateTime' }
            updated_at: { $ref: '#/components/schemas/DateTime' }
    IssuedToken:
      allOf:
        - $ref: '#/components/schemas/Session'
        - type: object
          required: [token]
          properties: { token: { type: string } }
    SessionResponse: { $ref: '#/components/schemas/SessionEnvelope' }
    SessionEnvelope:
      type: object
      required: [data]
      properties:
        data:
          allOf:
            - $ref: '#/components/schemas/Session'
            - type: object
              required: [can_manage_identities]
              properties:
                can_manage_identities:
                  type: boolean
                  description: True only for the authenticated deployment Admin Token when identity management is configured. UI capability only; management endpoints independently authorize the credential. False for ordinary Identity and Trusted Mode sessions.
                display_name:
                  type: string
                  const: system admin
                  description: Presentation only; included for an authenticated deployment Admin Token session, omitted for ordinary Identity and Trusted Mode sessions. Never used for authorization or actor attribution.
    IdentityResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Identity' } }
    IdentityListResponse:
      type: object
      required: [data]
      properties: { data: { type: array, items: { $ref: '#/components/schemas/Identity' } } }
    IssuedTokenResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/IssuedToken' } }
    CreateIdentityRequest:
      type: object
      additionalProperties: false
      required: [id, kind]
      properties:
        id: { $ref: '#/components/schemas/ActorID' }
        kind: { $ref: '#/components/schemas/ActorKind' }
        role: { type: string, description: "Trimmed by the server. Required and nonempty for Agent; empty or omitted for Human." }
    DefinitionMetadata:
      type: object
      required: [id, version, name, description, agent_instructions, suggested_tags, created_at, updated_at]
      properties:
        id: { type: string, pattern: '^[a-z0-9-]+$' }
        version: { type: integer, format: int64, minimum: 1 }
        name: { type: string }
        description: { type: string }
        agent_instructions: { type: string }
        suggested_tags: { $ref: '#/components/schemas/StringArray' }
        created_at: { $ref: '#/components/schemas/DateTime' }
        updated_at: { $ref: '#/components/schemas/DateTime' }
    CreateDefinitionRequest:
      type: object
      additionalProperties: false
      required: [name]
      properties:
        base_version:
          type: integer
          format: int64
          minimum: 1
          description: Required when appending to an existing Definition and must equal its latest stored version; omit for a new Definition ID.
        name: { type: string }
        description: { type: string }
        agent_instructions: { type: string }
        suggested_tags: { $ref: '#/components/schemas/StringArray' }
    ArtifactDefinition:
      type: object
      additionalProperties: false
      required: [name, description]
      properties:
        name: { type: string }
        description: { type: string }
    WorkflowTaskDefinition:
      type: object
      required: [id, title, description, acceptance_criteria, executor, allowed_roles, execution, review_policy, default_tags, artifacts]
      properties:
        id: { type: string }
        title: { type: string }
        description: { type: string }
        acceptance_criteria: { type: string }
        executor: { $ref: '#/components/schemas/ExecutorRequirement' }
        allowed_roles: { $ref: '#/components/schemas/StringArray' }
        execution: { type: string, enum: [required, optional] }
        review_policy: { type: string, enum: [none, executor_decides, required] }
        default_tags: { $ref: '#/components/schemas/StringArray' }
        artifacts: { type: array, items: { $ref: '#/components/schemas/ArtifactDefinition' } }
    WorkflowRelationDefinition:
      type: object
      required: [id, from_task_id, to_task_id, label, agent_guidance]
      properties:
        id: { type: string }
        from_task_id: { type: string }
        to_task_id: { type: string }
        label: { type: string }
        agent_guidance: { type: string }
    WorkflowGraph:
      type: object
      required: [start_task_ids, tasks, relations, max_task_instances_per_node]
      properties:
        start_task_ids:
          allOf:
            - $ref: '#/components/schemas/StringArray'
          uniqueItems: true
        tasks: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/WorkflowTaskDefinition' } }
        relations: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/WorkflowRelationDefinition' } }
        max_task_instances_per_node: { type: integer, minimum: 0, maximum: 500, description: "Shared limit on Task instances per Definition node within one WorkItem, including start and skipped instances. Other nodes have independent counts; reclaiming the same Task does not count again; Workflow retry creates and counts a new instance. No total Workflow Task limit. Zero uses the server default of 100." }
    WorkflowDefinition:
      allOf:
        - $ref: '#/components/schemas/DefinitionMetadata'
        - type: object
          required: [graph]
          properties: { graph: { $ref: '#/components/schemas/WorkflowGraph' } }
    BlackboardDefinition: { $ref: '#/components/schemas/DefinitionMetadata' }
    CreateWorkflowDefinitionRequest:
      type: object
      additionalProperties: false
      required: [name, graph]
      properties:
        base_version:
          type: integer
          format: int64
          minimum: 1
          description: Required when appending to an existing Definition and must equal its latest stored version; omit for a new Definition ID.
        name: { type: string }
        description: { type: string }
        agent_instructions: { type: string }
        suggested_tags: { $ref: '#/components/schemas/StringArray' }
        graph: { $ref: '#/components/schemas/WorkflowGraphRequest' }
    WorkflowGraphRequest:
      type: object
      additionalProperties: false
      required: [start_task_ids, tasks]
      properties:
        start_task_ids:
          allOf:
            - $ref: '#/components/schemas/StringArray'
          uniqueItems: true
        tasks: { type: array, maxItems: 100, items: { $ref: '#/components/schemas/WorkflowTaskDefinitionRequest' } }
        relations: { type: array, maxItems: 1000, items: { $ref: '#/components/schemas/WorkflowRelationDefinitionRequest' } }
        max_task_instances_per_node: { type: integer, minimum: 0, maximum: 500, default: 0, description: "Shared limit on Task instances per Definition node within one WorkItem, including start and skipped instances. Other nodes have independent counts; reclaiming the same Task does not count again; Workflow retry creates and counts a new instance. No total Workflow Task limit. Zero uses the server default of 100." }
    WorkflowTaskDefinitionRequest:
      type: object
      additionalProperties: false
      required: [id, title, executor, execution, review_policy]
      properties:
        id: { type: string }
        title: { type: string }
        description: { type: string }
        acceptance_criteria: { type: string }
        executor: { $ref: '#/components/schemas/ExecutorRequirement' }
        allowed_roles: { $ref: '#/components/schemas/StringArray' }
        execution: { type: string, enum: [required, optional] }
        review_policy: { type: string, enum: [none, executor_decides, required] }
        default_tags: { $ref: '#/components/schemas/StringArray' }
        artifacts: { type: array, items: { $ref: '#/components/schemas/ArtifactDefinition' } }
    WorkflowRelationDefinitionRequest:
      type: object
      additionalProperties: false
      required: [id, from_task_id, to_task_id]
      properties:
        id: { type: string }
        from_task_id: { type: string }
        to_task_id: { type: string }
        label: { type: string }
        agent_guidance: { type: string }
    WorkflowDefinitionResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/WorkflowDefinition' } }
    WorkflowDefinitionListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/WorkflowDefinition' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    BlackboardDefinitionResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/BlackboardDefinition' } }
    BlackboardDefinitionListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/BlackboardDefinition' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    DefinitionBinding:
      type: object
      required: [id, version, mode]
      properties:
        id: { type: string, pattern: '^[a-z0-9-]+$' }
        version: { type: integer, format: int64 }
        mode: { $ref: '#/components/schemas/CoordinationMode' }
    WorkItem:
      type: object
      required: [id, definition, status, acceptance_mode, title, goal, context, constraints, acceptance_criteria, tags, result, version, created_at, updated_at, completed_at, cancelled_at, cancelled_by, cancellation_reason, failure, workflow_max_task_instances_per_node, started_over_from_work_item_id, start_over_context, recovery_instructions]
      properties:
        id: { type: string }
        definition: { $ref: '#/components/schemas/DefinitionBinding' }
        status: { $ref: '#/components/schemas/WorkItemStatus' }
        acceptance_mode: { type: string, enum: [none, agent, human] }
        title: { type: string }
        goal: { type: string }
        context: { type: string }
        constraints: { type: string }
        acceptance_criteria: { type: string }
        tags: { $ref: '#/components/schemas/StringArray' }
        result:
          $ref: '#/components/schemas/HistoryText'
          description: Blackboard completion proposal or accepted outcome. Always empty for Workflow WorkItems; inspect Task Submissions and Artifacts for Workflow outcomes.
        version: { type: integer, format: int64 }
        created_at: { $ref: '#/components/schemas/DateTime' }
        updated_at: { $ref: '#/components/schemas/DateTime' }
        completed_at: { $ref: '#/components/schemas/NullableDateTime' }
        cancelled_at: { $ref: '#/components/schemas/NullableDateTime' }
        cancelled_by: { $ref: '#/components/schemas/NullableActorRef' }
        cancellation_reason: { $ref: '#/components/schemas/HistoryText' }
        started_over_from_work_item_id: { $ref: '#/components/schemas/NullableString', description: 'Immutable source reference to another Workflow WorkItem with the same Definition ID and version; null when not started over.' }
        start_over_context: { $ref: '#/components/schemas/HistoryText', description: Current failure reasons and source ID for a Workflow created by Start over, bounded to 32768 UTF-8 bytes; old execution history is not copied. Empty otherwise. }
        recovery_instructions: { $ref: '#/components/schemas/HistoryText', description: Operator guidance for the current continue/start-over; empty by default. }
        workflow_max_task_instances_per_node:
          type: integer
          minimum: 0
          maximum: 500
          description: Workflow-only per-WorkItem override, applied independently to every node. Zero inherits the bound Definition limit. Always zero for Blackboard.
        failure:
          description: Current failure snapshot; null before failure and after recovery. The original reason remains in event history. Historical records without a failure event can remain null.
          oneOf:
            - $ref: '#/components/schemas/WorkItemFailure'
            - type: 'null'
    WorkItemFailure:
      type: object
      required: [kind, message, workflow_task_id, task_instances, limit]
      properties:
        kind: { type: string, enum: [execution_failure, workflow_task_instance_limit] }
        message: { $ref: '#/components/schemas/HistoryText', description: 'Required nonblank failure explanation (not only whitespace). Generated node-limit messages use a brief explanation if full detail would exceed 32768 UTF-8 bytes. The complete blocked node ID remains in workflow_task_id.' }
        workflow_task_id: { type: string, description: Complete blocked Definition node ID for a per-node guard even when message is abbreviated; empty for ordinary or legacy failures. }
        task_instances: { type: integer, minimum: 0, description: Materialized instance count at a per-node failure; zero otherwise. }
        limit: { type: integer, minimum: 0, maximum: 500, description: Limit that triggered the guard; zero for ordinary failures. }
    CreateWorkItemRequest:
      type: object
      additionalProperties: false
      required: [definition_id, mode, title, goal]
      properties:
        definition_id: { type: string, pattern: '^[a-z0-9-]+$' }
        mode: { $ref: '#/components/schemas/CoordinationMode' }
        title: { type: string }
        goal: { type: string }
        context: { type: string }
        constraints: { type: string }
        acceptance_criteria: { type: string }
        acceptance_mode: { type: string, enum: [none, agent, human], default: none }
        tags: { $ref: '#/components/schemas/StringArray' }
    Review:
      type: object
      required: [id, task_id, submission_id, status, requested_by, requested_at, decided_by, decided_at, feedback]
      properties:
        id: { type: string }
        task_id: { type: string }
        submission_id: { $ref: '#/components/schemas/NullableString' }
        status: { type: string, enum: [pending, approved, rejected] }
        requested_by: { type: string }
        requested_at: { $ref: '#/components/schemas/DateTime' }
        decided_by: { $ref: '#/components/schemas/NullableString' }
        decided_at: { $ref: '#/components/schemas/NullableDateTime' }
        feedback: { $ref: '#/components/schemas/HistoryText' }
    Submission:
      type: object
      required: [id, task_id, claim_id, result, submitted_at]
      properties:
        id: { type: string }
        task_id: { type: string }
        claim_id: { type: string }
        result: { $ref: '#/components/schemas/HistoryText' }
        submitted_at: { $ref: '#/components/schemas/DateTime' }
    Failure:
      type: object
      required: [id, task_id, claim_id, action, reason, retry_prompt, failed_at]
      properties:
        id: { type: string }
        task_id: { type: string }
        claim_id: { type: string }
        action: { type: string, enum: [retry, await_human, fail_work_item], description: "Workflow retry creates a new attempt; await_human stops only the Workflow Task for Human Continue execution; fail_work_item stops all work. Blackboard retry reuses the same Task. Blackboard await_human is rejected without state changes, including at the failure-history limit." }
        reason: { $ref: '#/components/schemas/HistoryText' }
        retry_prompt: { $ref: '#/components/schemas/HistoryText', description: Guidance for the next attempt; nonempty only for action retry. }
        failed_at: { $ref: '#/components/schemas/DateTime' }
    TransitionDecision:
      type: object
      required: [id, work_item_id, source_task_id, source_submission_id, choice_group_id, triggered_relation_ids, skipped_relation_ids, review_requested_relation_ids, reason, skip_task_ids, review_requested_task_ids, decided_by, decided_at, applied_at]
      properties:
        id: { type: string }
        work_item_id: { type: string }
        source_task_id: { type: string }
        source_submission_id: { $ref: '#/components/schemas/NullableString' }
        choice_group_id: { type: string }
        triggered_relation_ids: { $ref: '#/components/schemas/StringArray' }
        skipped_relation_ids: { $ref: '#/components/schemas/StringArray' }
        review_requested_relation_ids: { $ref: '#/components/schemas/StringArray' }
        reason: { $ref: '#/components/schemas/HistoryText' }
        skip_task_ids: { $ref: '#/components/schemas/StringArray' }
        review_requested_task_ids: { $ref: '#/components/schemas/StringArray' }
        decided_by: { $ref: '#/components/schemas/ActorRef' }
        decided_at: { $ref: '#/components/schemas/DateTime' }
        applied_at: { $ref: '#/components/schemas/NullableDateTime' }
    Task:
      type: object
      description: Task histories are complete. Each Task accepts at most 128 Claims, 64 Submissions, 64 Reviews, 64 ordinary Failures, 64 Transition Decisions, and 64 Artifacts. A fail_work_item Failure that ends the current Task may add one final record; attempting to append beyond any history ceiling fails the WorkItem and ends active Claims.
      required: [id, work_item_id, workflow_task_id, workflow_activation_id, retry_of_task_id, retry_context, retry_instructions, status, active_claim_id, parent_task_id, decomposed_at, title, description, acceptance_criteria, executor, skipped_by, skip_reason, allowed_roles, tags, execution, review_policy, reviews, submissions, failures, transition_decisions, position, version, created_at, updated_at, completed_at]
      properties:
        id: { type: string }
        work_item_id: { type: string }
        workflow_task_id: { $ref: '#/components/schemas/NullableString' }
        workflow_activation_id: { $ref: '#/components/schemas/NullableString' }
        retry_of_task_id: { $ref: '#/components/schemas/NullableString', description: Previous Workflow attempt replaced by this Task; null otherwise. }
        retry_context: { $ref: '#/components/schemas/HistoryText', description: 'Bounded recovery summary prioritizing current failure and interruption causes before earlier history. Full retry instructions remain in retry_instructions.' }
        retry_instructions: { $ref: '#/components/schemas/HistoryText', description: 'Retry guidance from action retry or Human instructions, kept separately from the bounded summary. Uses the first nonempty value from current Human instructions, the source attempt latest retry failure retry_prompt (including a limit-blocked retry), and inherited retry_instructions.' }
        status: { $ref: '#/components/schemas/TaskStatus' }
        active_claim_id: { $ref: '#/components/schemas/NullableString' }
        parent_task_id: { $ref: '#/components/schemas/NullableString' }
        decomposed_at: { $ref: '#/components/schemas/NullableDateTime' }
        title: { type: string }
        description: { type: string }
        acceptance_criteria: { type: string }
        executor: { $ref: '#/components/schemas/ExecutorRequirement' }
        skipped_by:
          oneOf: [{ $ref: '#/components/schemas/ActorRef' }, { type: 'null' }]
        skip_reason: { $ref: '#/components/schemas/HistoryText' }
        allowed_roles: { $ref: '#/components/schemas/StringArray' }
        tags: { $ref: '#/components/schemas/StringArray' }
        execution: { type: [string, 'null'], enum: [required, optional, null] }
        review_policy: { type: [string, 'null'], enum: [none, executor_decides, required, null] }
        reviews: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Review' } }
        submissions: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Submission' } }
        failures: { type: array, maxItems: 65, items: { $ref: '#/components/schemas/Failure' } }
        transition_decisions: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/TransitionDecision' } }
        position: { type: integer, format: int64 }
        version: { type: integer, format: int64 }
        created_at: { $ref: '#/components/schemas/DateTime' }
        updated_at: { $ref: '#/components/schemas/DateTime' }
        completed_at: { $ref: '#/components/schemas/NullableDateTime' }
    TaskDraftRequest:
      type: object
      description: The Blackboard WorkItem has hard ceilings of 1,000 Task instances and 10,000 suggested Relations, including completed history and decomposition children. Requests that would exceed a ceiling return 409 conflict.
      additionalProperties: false
      required: [title, executor]
      properties:
        coordination_claim_id: { type: string, description: Required for an Agent when creating the Task resolves a lifecycle candidate. }
        title: { type: string }
        description: { type: string }
        acceptance_criteria: { type: string }
        executor: { $ref: '#/components/schemas/ExecutorRequirement' }
        allowed_roles: { $ref: '#/components/schemas/StringArray' }
        tags: { $ref: '#/components/schemas/StringArray' }
    AddRelationRequest:
      type: object
      description: A Blackboard WorkItem accepts at most 10,000 suggested Relations. Requests beyond that hard ceiling return 409 conflict.
      additionalProperties: false
      required: [from_task_id, to_task_id]
      properties:
        from_task_id: { type: string }
        to_task_id: { type: string }
    Claim:
      type: object
      required: [id, task_id, executor, claimed_at, last_heartbeat_at, lease_until, lease_seconds, ended_at, end_reason]
      properties:
        id: { type: string }
        task_id: { type: string }
        executor: { $ref: '#/components/schemas/ActorRef' }
        claimed_at: { $ref: '#/components/schemas/DateTime' }
        last_heartbeat_at: { $ref: '#/components/schemas/DateTime' }
        lease_until: { $ref: '#/components/schemas/DateTime' }
        lease_seconds: { type: integer, format: int64 }
        ended_at: { $ref: '#/components/schemas/NullableDateTime' }
        end_reason: { type: string, enum: ['', task_completed, submitted_for_review, released, revoked, task_failed, task_decomposed, expired, work_item_cancelled] }
    CoordinationClaim:
      type: object
      required: [id, work_item_id, kind, executor, claimed_at, last_heartbeat_at, lease_until, lease_seconds, ended_at, end_reason]
      properties:
        id: { type: string }
        work_item_id: { type: string }
        kind: { type: string, enum: [empty_blackboard, blackboard_completion, work_item_acceptance] }
        executor: { $ref: '#/components/schemas/ActorRef' }
        claimed_at: { $ref: '#/components/schemas/DateTime' }
        last_heartbeat_at: { $ref: '#/components/schemas/DateTime' }
        lease_until: { $ref: '#/components/schemas/DateTime' }
        lease_seconds: { type: integer, format: int64, minimum: 1 }
        ended_at: { $ref: '#/components/schemas/NullableDateTime' }
        end_reason:
          type: string
          enum: ['', task_created, completion_submitted, completion_accepted, released, expired, revoked, work_item_cancelled, work_item_failed]
          description: task_created is valid for every kind; completion_submitted is valid for empty_blackboard and blackboard_completion; completion_accepted is valid for work_item_acceptance; operational end reasons are valid for every kind.
    CoordinationClaimRequest:
      type: object
      additionalProperties: false
      required: [kind]
      properties:
        kind: { type: string, enum: [empty_blackboard, blackboard_completion, work_item_acceptance] }
        executor_token: { $ref: '#/components/schemas/ExecutorToken' }
        lease_seconds:
          type: integer
          format: int64
          default: 0
          description: Positive values are clamped to the supported 15-1800 second range; zero or a negative value uses the server default.
    Artifact:
      type: object
      required: [id, work_item_id, task_id, claim_id, submission_id, name, uri, created_at]
      properties:
        id: { type: string }
        work_item_id: { type: string }
        task_id: { type: string }
        claim_id: { type: string }
        submission_id: { $ref: '#/components/schemas/NullableString' }
        name: { type: string }
        uri: { type: string, format: uri }
        created_at: { $ref: '#/components/schemas/DateTime' }
    TaskRelation:
      type: object
      required: [work_item_id, from_task_id, to_task_id, created_at]
      properties:
        work_item_id: { type: string }
        from_task_id: { type: string }
        to_task_id: { type: string }
        created_at: { $ref: '#/components/schemas/DateTime' }
    DefinitionContext:
      type: object
      required: [name, description, agent_instructions, suggested_tags]
      properties:
        name: { type: string }
        description: { type: string }
        agent_instructions: { type: string }
        suggested_tags: { $ref: '#/components/schemas/StringArray' }
    Responsibility:
      type: object
      required: [kind, actor]
      properties:
        kind: { type: string }
        actor:
          oneOf: [{ $ref: '#/components/schemas/ActorRef' }, { type: 'null' }]
    Outcome:
      type: object
      required: [kind, actor, reason, occurred_at]
      properties:
        kind: { type: string }
        actor:
          oneOf: [{ $ref: '#/components/schemas/ActorRef' }, { type: 'null' }]
        reason: { $ref: '#/components/schemas/HistoryText' }
        occurred_at: { $ref: '#/components/schemas/NullableDateTime' }
    TaskHistory:
      type: object
      required: [claims, submissions, reviews, failures, transition_decisions]
      properties:
        claims: { type: array, maxItems: 128, items: { $ref: '#/components/schemas/Claim' } }
        submissions: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Submission' } }
        reviews: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Review' } }
        failures: { type: array, maxItems: 65, items: { $ref: '#/components/schemas/Failure' } }
        transition_decisions: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/TransitionDecision' } }
    TaskCapabilities:
      type: object
      required: [can_claim, can_submit, can_release, can_fail, can_review, can_skip, can_decompose, can_add_child]
      properties:
        can_claim: { type: boolean }
        can_submit: { type: boolean }
        can_release: { type: boolean }
        can_fail: { type: boolean }
        can_review: { type: boolean }
        can_skip: { type: boolean }
        can_decompose: { type: boolean }
        can_add_child: { type: boolean }
    TaskDetail:
      type: object
      required: [task, responsibility, outcome, current_review, history, artifacts, capabilities]
      properties:
        task: { $ref: '#/components/schemas/Task' }
        responsibility: { $ref: '#/components/schemas/Responsibility' }
        outcome: { $ref: '#/components/schemas/Outcome' }
        current_review:
          oneOf: [{ $ref: '#/components/schemas/Review' }, { type: 'null' }]
        history: { $ref: '#/components/schemas/TaskHistory' }
        artifacts: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Artifact' } }
        capabilities: { $ref: '#/components/schemas/TaskCapabilities' }
    WorkflowChoiceRelation:
      type: object
      required: [relation_id, target, label, agent_guidance]
      properties:
        relation_id: { type: string }
        target: { $ref: '#/components/schemas/WorkflowTaskDefinition' }
        label: { type: string }
        agent_guidance: { type: string }
    WorkflowChoiceOption:
      type: object
      required: [id, kind, targets, relations, skippable_optional_tasks]
      properties:
        id: { type: string }
        kind: { type: string, enum: [continue, exit] }
        targets: { type: array, items: { $ref: '#/components/schemas/WorkflowTaskDefinition' } }
        relations: { type: array, items: { $ref: '#/components/schemas/WorkflowChoiceRelation' } }
        skippable_optional_tasks: { type: array, items: { $ref: '#/components/schemas/WorkflowTaskDefinition' } }
    WorkflowContext:
      type: object
      required: [upstream_tasks, choice_groups]
      properties:
        upstream_tasks: { type: array, items: { $ref: '#/components/schemas/Task' } }
        choice_groups: { type: array, items: { $ref: '#/components/schemas/WorkflowChoiceOption' } }
    BlackboardContext:
      type: object
      required: [current_task_id, tasks, relations, can_decompose]
      properties:
        current_task_id: { type: string }
        tasks: { type: array, items: { $ref: '#/components/schemas/Task' } }
        relations: { type: array, items: { $ref: '#/components/schemas/TaskRelation' } }
        can_decompose: { type: boolean }
    ArtifactSubmission:
      type: object
      description: Artifacts grouped by the exact originating Submission; none means no Review was requested.
      required: [task_id, submission_id, submitted_at, review_status, artifacts]
      properties:
        task_id: { type: string }
        submission_id: { type: string }
        submitted_at: { type: string, format: date-time }
        review_status: { type: string, enum: [none, pending, approved, rejected] }
        artifacts: { type: array, maxItems: 64, items: { $ref: '#/components/schemas/Artifact' } }
    TaskContext:
      type: object
      required: [work_item, task, claims, staged_artifacts, input_artifacts, shared_artifacts, expected_artifacts, definition, responsibility, outcome, workflow, blackboard]
      properties:
        work_item: { $ref: '#/components/schemas/WorkItem' }
        task: { $ref: '#/components/schemas/Task' }
        claims: { type: array, maxItems: 128, items: { $ref: '#/components/schemas/Claim' } }
        staged_artifacts:
          type: array
          maxItems: 64
          description: Unsubmitted artifacts of the current Active Task Claim, visible only to its owner. Empty without an owned active Claim.
          items: { $ref: '#/components/schemas/Artifact' }
        input_artifacts:
          type: array
          description: Workflow only. Exact direct input Submissions selected by this activation's applied decision receipts. No global newest-by-name selection or ancestor fallback; skipped sources and sources without artifacts contribute no group. Empty in Blackboard.
          items: { $ref: '#/components/schemas/ArtifactSubmission' }
        shared_artifacts:
          type: array
          description: Blackboard only. All submitted WorkItem artifact history grouped by Submission, including pending and rejected Reviews. Shared evidence is not an authoritative dependency input. Empty in Workflow.
          items: { $ref: '#/components/schemas/ArtifactSubmission' }
        expected_artifacts: { type: array, items: { $ref: '#/components/schemas/ArtifactDefinition' } }
        definition: { $ref: '#/components/schemas/DefinitionContext' }
        responsibility: { $ref: '#/components/schemas/Responsibility' }
        outcome: { $ref: '#/components/schemas/Outcome' }
        workflow:
          oneOf: [{ $ref: '#/components/schemas/WorkflowContext' }, { type: 'null' }]
        blackboard:
          oneOf: [{ $ref: '#/components/schemas/BlackboardContext' }, { type: 'null' }]
    WorkItemContext:
      type: object
      required: [work_item, definition, tasks, relations, claims, active_claims, coordination_claims, active_coordination_claim, artifacts, recovery_task_ids]
      properties:
        recovery_task_ids:
          type: array
          items: { type: string }
          description: HTTP console projection of current Tasks that Continue would replace, including failed and interrupted attempts. Empty when none, including Blackboard. Uses the same selection as recovery; version and capacity are revalidated on submission. Not stored or exposed as an Agent MCP action.
        work_item: { $ref: '#/components/schemas/WorkItem' }
        definition: { $ref: '#/components/schemas/DefinitionContext' }
        tasks: { type: array, items: { $ref: '#/components/schemas/Task' } }
        relations: { type: array, items: { $ref: '#/components/schemas/TaskRelation' } }
        claims: { type: array, items: { $ref: '#/components/schemas/Claim' } }
        active_claims: { type: array, items: { $ref: '#/components/schemas/Claim' } }
        coordination_claims: { type: array, maxItems: 128, items: { $ref: '#/components/schemas/CoordinationClaim' } }
        active_coordination_claim:
          oneOf: [{ $ref: '#/components/schemas/CoordinationClaim' }, { type: 'null' }]
        artifacts: { type: array, items: { $ref: '#/components/schemas/Artifact' } }
    WorkCandidate:
      type: object
      required: [kind, work_item, task, definition]
      properties:
        kind: { type: string, enum: [task, empty_blackboard, blackboard_completion, work_item_acceptance] }
        work_item: { $ref: '#/components/schemas/WorkItem' }
        task:
          oneOf: [{ $ref: '#/components/schemas/Task' }, { type: 'null' }]
        definition: { $ref: '#/components/schemas/DefinitionContext' }
    HumanAttentionItem:
      type: object
      required: [kind, work_item, task]
      properties:
        kind: { type: string, enum: [review, human_task, work_item_acceptance, workflow_recovery] }
        work_item: { $ref: '#/components/schemas/WorkItem' }
        task:
          oneOf: [{ $ref: '#/components/schemas/Task' }, { type: 'null' }]
    LeaseRequest:
      type: object
      additionalProperties: false
      properties:
        lease_seconds:
          type: integer
          format: int64
          default: 0
          description: Positive values are clamped to the supported 15-1800 second range; zero or a negative value uses the server default.
    TaskClaimRequest:
      type: object
      additionalProperties: false
      properties:
        executor_token: { $ref: '#/components/schemas/ExecutorToken' }
        lease_seconds:
          type: integer
          format: int64
          default: 0
          description: Positive values are clamped to the supported 15-1800 second range; zero or a negative value uses the server default.
    ExecutorToken:
      type: string
      oneOf:
        - const: ''
        - minLength: 53
          maxLength: 53
          pattern: '^krs_claim_[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$'
      writeOnly: true
      description: Optional client-generated Claim credential containing 256 random bits as canonical unpadded base64url. Omitted or empty means no Executor credential. Core stores only its SHA-256 hash.
    WorkflowTransitionRequest:
      type: object
      additionalProperties: false
      required: [choice_group_id]
      properties:
        choice_group_id: { type: string }
        skip_optional_task_ids: { $ref: '#/components/schemas/StringArray' }
        review_skipped_task_ids: { $ref: '#/components/schemas/StringArray' }
        reason: { $ref: '#/components/schemas/HistoryText' }
    SubmitTaskRequest:
      type: object
      additionalProperties: false
      required: [claim_id, result]
      properties:
        claim_id: { type: string }
        result: { $ref: '#/components/schemas/HistoryText' }
        artifact_ids: { $ref: '#/components/schemas/StringArray' }
        request_review: { type: boolean, default: false }
        transition:
          oneOf: [{ $ref: '#/components/schemas/WorkflowTransitionRequest' }, { type: 'null' }]
    CreateArtifactRequest:
      type: object
      additionalProperties: false
      required: [claim_id, name, uri]
      properties:
        claim_id: { type: string }
        name: { type: string }
        uri: { type: string, format: uri }
    FailTaskRequest:
      type: object
      additionalProperties: false
      required: [claim_id, action, reason]
      properties:
        claim_id: { type: string }
        action: { type: string, enum: [retry, await_human, fail_work_item], description: "Workflow retry creates a new attempt; await_human stops only the Workflow Task for Human Continue execution; fail_work_item stops all work. Blackboard retry reuses the same Task. Blackboard await_human is rejected without state changes, including at the failure-history limit." }
        reason: { $ref: '#/components/schemas/HistoryText' }
        retry_prompt: { $ref: '#/components/schemas/HistoryText', description: Guidance for the next attempt; nonempty only for action retry. }
    WorkItemResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/WorkItem' } }
    WorkItemListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/WorkItem' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    TaskResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Task' } }
    TaskRelationResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/TaskRelation' } }
    ClaimResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Claim' } }
    CoordinationClaimResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/CoordinationClaim' } }
    SubmissionResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Submission' } }
    ArtifactResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Artifact' } }
    ArtifactListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/Artifact' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    FailureResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Failure' } }
    ReviewResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/Review' } }
    TaskDetailResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/TaskDetail' } }
    TaskContextResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/TaskContext' } }
    WorkItemContextResponse:
      type: object
      required: [data]
      properties: { data: { $ref: '#/components/schemas/WorkItemContext' } }
    WorkCandidateListResponse:
      type: object
      required: [data]
      properties: { data: { type: array, items: { $ref: '#/components/schemas/WorkCandidate' } } }
    HumanAttentionListResponse:
      type: object
      required: [data, next_cursor]
      properties:
        data: { type: array, items: { $ref: '#/components/schemas/HumanAttentionItem' } }
        next_cursor: { $ref: '#/components/schemas/NullableCursor' }
    DecompositionResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [parent, children]
          properties:
            parent: { $ref: '#/components/schemas/Task' }
            children: { type: array, items: { $ref: '#/components/schemas/Task' } }
