> ## Documentation Index
> Fetch the complete documentation index at: https://help.harmonica.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# Inspect host-authorized chain state and blockers

> Inspect a chain using any of its session IDs. Requires owner/admin access
to the origin (step-zero) session; ownership of a later session or project
editor membership alone is insufficient. Returns stable chain, step and
session IDs without prompts, summaries, roster emails or participant text.
A read makes no state changes. can_advance is advisory; continue rechecks
eligibility under the existing runtime's chain lock.




## OpenAPI

````yaml /api-reference/openapi.yaml get /sessions/{id}/chain-state
openapi: 3.1.0
info:
  title: Harmonica API
  version: 1.0.0
  description: >
    REST API for the Harmonica structured deliberation platform.

    Provides access to sessions and their data, including creating, updating,
    and querying sessions, plus response submission for active sessions.
  contact:
    name: Harmonica
    url: https://harmonica.chat
servers:
  - url: https://app.harmonica.chat/api/v1
    description: Production
  - url: http://localhost:3000/api/v1
    description: Local development
security:
  - apiKey: []
paths:
  /sessions/{id}/chain-state:
    get:
      tags:
        - Sessions
      summary: Inspect host-authorized chain state and blockers
      description: >
        Inspect a chain using any of its session IDs. Requires owner/admin
        access

        to the origin (step-zero) session; ownership of a later session or
        project

        editor membership alone is insufficient. Returns stable chain, step and

        session IDs without prompts, summaries, roster emails or participant
        text.

        A read makes no state changes. can_advance is advisory; continue
        rechecks

        eligibility under the existing runtime's chain lock.
      operationId: getChainState
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Chain state and actionable blockers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainControlState'
        '401':
          description: Authentication required
        '403':
          description: Owner or admin access to the origin required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChainControlError'
        '404':
          description: Session is not part of a chain or chain not found
        '500':
          description: Internal error
components:
  schemas:
    ChainControlState:
      type: object
      required:
        - chain_id
        - status
        - current_step_index
        - current_step_id
        - current_session_id
        - can_advance
        - blockers
        - completion_type
        - total_assignments
        - completed_assignments
        - required_assignments
        - timer_ready_at
        - steps
      properties:
        chain_id:
          type: string
        status:
          type: string
          enum:
            - pending
            - active
            - awaiting
            - paused
            - completed
            - failed
            - cancelled
        current_step_index:
          type: integer
        current_step_id:
          type:
            - string
            - 'null'
        current_session_id:
          type:
            - string
            - 'null'
        can_advance:
          type: boolean
          description: >-
            Advisory snapshot; eligibility is rechecked under the chain lock
            when continuing.
        blockers:
          type: array
          items:
            $ref: '#/components/schemas/ChainBlocker'
        completion_type:
          type: string
          enum:
            - host_continue
            - all_submitted
            - timer
            - quorum
            - quorum_percent
        total_assignments:
          type: integer
        completed_assignments:
          type: integer
        required_assignments:
          type:
            - integer
            - 'null'
          description: >-
            Completion threshold for assignment-based gates; zero assignments
            still cannot complete an automatic gate.
        timer_ready_at:
          type:
            - string
            - 'null'
          format: date-time
        steps:
          type: array
          items:
            $ref: '#/components/schemas/ChainStepState'
    ChainControlError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - forbidden
                - not_found
                - invalid_request
                - validation_error
                - stale_step
                - transition_blocked
                - advance_failed
                - internal_error
            message:
              type: string
            blockers:
              type: array
              items:
                $ref: '#/components/schemas/ChainBlocker'
    ChainBlocker:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          enum:
            - chain_not_active
            - step_not_active
            - invalid_snapshot
            - unassigned_roles
            - completion_not_met
            - summary_required
        message:
          type: string
        step_id:
          type: string
        session_id:
          type:
            - string
            - 'null'
    ChainStepState:
      type: object
      required:
        - step_id
        - step_index
        - template_step_id
        - session_id
        - status
        - title
      properties:
        step_id:
          type: string
        step_index:
          type: integer
        template_step_id:
          type: string
        session_id:
          type:
            - string
            - 'null'
        status:
          type: string
          enum:
            - pending
            - active
            - awaiting
            - completed
            - failed
            - skipped
        title:
          type: string
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: |
        API key authentication. Pass your key as a Bearer token.
        Keys use the format `hm_live_<32 hex chars>`.
        Generate keys from your Harmonica dashboard settings.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.