> ## 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.

# Read a chain's Business Model Canvas

> Reads only; never generates a Canvas. All responses use private, no-store.
Authenticated accounts (API key or browser session) need workspace viewer
access and access to the results audience of every source session. A
host-only source requires owner/admin access to that source; a workspace
editor role alone does not override the source's audience.

Alternatively, pass the signed invitation identity in
x-chain-participant-token and select stepIndex or closing=true. The server
rechecks membership in this chain, withdrawal, participant sharing and the
requested round. Review rounds need an eligible assignment, cannot be in
the future, and return their immutable bound revision. Closing reads need
a completed chain and an approved closing revision. A valid token plus a
round/closing selector requests the participant projection even when the
caller is also signed in. It grants no workspace role, candidate history,
original-contribution access or arbitrary revision selection.

Source changes may withhold state on management reads while preserving
recovery controls; stale participant snapshots fail closed. Review and
evidence status remain distinct. A filled Canvas is not proof of agreement,
market demand or viability. Rendered/exported adaptations retain visible
Strategyzer.com credit and the original/adaptation license notices.




## OpenAPI

````yaml /api-reference/openapi.yaml get /chains/{instanceId}/bmc
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:
  /chains/{instanceId}/bmc:
    get:
      tags:
        - Chains
      summary: Read a chain's Business Model Canvas
      description: >
        Reads only; never generates a Canvas. All responses use private,
        no-store.

        Authenticated accounts (API key or browser session) need workspace
        viewer

        access and access to the results audience of every source session. A

        host-only source requires owner/admin access to that source; a workspace

        editor role alone does not override the source's audience.


        Alternatively, pass the signed invitation identity in

        x-chain-participant-token and select stepIndex or closing=true. The
        server

        rechecks membership in this chain, withdrawal, participant sharing and
        the

        requested round. Review rounds need an eligible assignment, cannot be in

        the future, and return their immutable bound revision. Closing reads
        need

        a completed chain and an approved closing revision. A valid token plus a

        round/closing selector requests the participant projection even when the

        caller is also signed in. It grants no workspace role, candidate
        history,

        original-contribution access or arbitrary revision selection.


        Source changes may withhold state on management reads while preserving

        recovery controls; stale participant snapshots fail closed. Review and

        evidence status remain distinct. A filled Canvas is not proof of
        agreement,

        market demand or viability. Rendered/exported adaptations retain visible

        Strategyzer.com credit and the original/adaptation license notices.
      operationId: getBusinessModelCanvas
      parameters:
        - $ref: '#/components/parameters/chainInstanceId'
        - name: stepIndex
          in: query
          required: false
          description: >-
            Zero-based review step for a participant read; must be at least 1
            and no later than the current step. Ignored for an authorized
            management projection.
          schema:
            type: integer
            minimum: 0
            maximum: 9007199254740991
        - name: closing
          in: query
          required: false
          description: >-
            Literal true selects the approved closing revision for a
            participant; takes precedence over stepIndex. Ignored for a
            management projection.
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: Authorized management state or one participant-bound revision.
          headers:
            Cache-Control:
              schema:
                type: string
              description: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcReadResponse'
        '400':
          description: Invalid round index.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '401':
          description: No authenticated account or valid signed participant identity.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '403':
          description: >-
            Workspace/source access denied or participant sharing disabled
            (bmc_sharing_disabled).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '404':
          description: >-
            Chain absent or not BMC, participant not admitted, or requested
            round not available.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '409':
          description: >-
            Bound snapshot missing (bmc_snapshot_missing) or its source changed
            (bmc_source_changed).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: The Canvas could not be loaded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
      security:
        - apiKey: []
        - chainParticipantToken: []
components:
  parameters:
    chainInstanceId:
      name: instanceId
      in: path
      required: true
      schema:
        type: string
        minLength: 1
      description: Existing BMC chain instance ID; each chain has its own Canvas.
  schemas:
    BmcReadResponse:
      type: object
      additionalProperties: false
      required:
        - state
        - canEdit
        - canApproveClosing
        - sourceStatus
        - management
        - preparation
        - boundSnapshotHeld
        - boundSnapshotMessage
      properties:
        state:
          description: >-
            Null when current source changes withhold the saved Canvas;
            management and readiness remain available for recovery.
          anyOf:
            - $ref: '#/components/schemas/BmcState'
            - type: 'null'
        canEdit:
          type: boolean
        canApproveClosing:
          type: boolean
          description: >-
            True only when an editor may approve the current closing Canvas
            after a completed chain and current final extraction.
        sourceStatus:
          type: string
          enum:
            - current
            - changed
        management:
          type: object
          additionalProperties: false
          required:
            - expectedRevision
            - participantSharingEnabled
          properties:
            expectedRevision:
              type: integer
              minimum: 0
            participantSharingEnabled:
              type: boolean
        preparation:
          type: array
          description: Per-round management status; empty for participant projections.
          items:
            $ref: '#/components/schemas/BmcPreparation'
        boundSnapshotHeld:
          type: boolean
          description: >-
            A bound review snapshot has a changed source. Preparing a
            replacement does not replace that immutable binding; restart in a
            fresh chain to continue the affected round.
        boundSnapshotMessage:
          type:
            - string
            - 'null'
    BmcError:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      description: >-
        BMC operation errors use this flat envelope. Authenticator failures on
        writes and rate limits use the standard nested Error envelope.
      properties:
        error:
          type: string
        code:
          type: string
          enum:
            - unauthorized
            - forbidden
            - not_found
            - validation_error
            - explicit_retry_required
            - bmc_changed
            - bmc_invalid_edit
            - bmc_source_missing
            - bmc_extraction_pending
            - bmc_extraction_failed
            - bmc_source_changed
            - bmc_review_required
            - bmc_snapshot_missing
            - bmc_sharing_disabled
            - internal_error
    BmcState:
      type: object
      additionalProperties: false
      required:
        - version
        - participantSharingEnabled
        - current
        - revisions
        - reviewedRevisionId
        - closingRevisionId
        - roundBindings
        - extractions
      description: >-
        Source-filtered state. A participant receives only the requested
        authorized review or approved closing revision, with no candidate
        history or extraction receipts. Management reads can include current
        preparation/history. Revision bindings refer to retained revisions;
        extraction keys are the decimal source stepIndex. Tombstones protect
        human removals on regeneration.
      properties:
        version:
          type: integer
          enum:
            - 1
        participantSharingEnabled:
          type: boolean
          default: true
        current:
          anyOf:
            - $ref: '#/components/schemas/BmcRevision'
            - type: 'null'
        revisions:
          type: array
          items:
            $ref: '#/components/schemas/BmcRevision'
        reviewedRevisionId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 200
        closingRevisionId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 200
        roundBindings:
          type: object
          description: >-
            Zero-based review step index (1 or later) mapped to its immutable
            revision ID; build-model has index 0 and no review binding.
          additionalProperties:
            $ref: '#/components/schemas/BmcId'
        removedEntryIds:
          type: array
          items:
            $ref: '#/components/schemas/BmcId'
        removedEntryKeys:
          type: array
          items:
            type: string
            pattern: ^[a-f0-9]{64}$
        extractions:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/BmcExtractionState'
    BmcPreparation:
      type: object
      additionalProperties: false
      required:
        - stepIndex
        - title
        - status
        - canPrepare
      properties:
        stepIndex:
          type: integer
          minimum: 0
        title:
          type: string
        status:
          type: string
          enum:
            - not_prepared
            - pending
            - ready
            - error
            - stale
            - unavailable
        canPrepare:
          type: boolean
          description: >-
            Advisory editor action eligibility, rechecked under lock when
            preparing. A new model call may incur cost.
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              enum:
                - unauthorized
                - forbidden
                - not_found
                - validation_error
                - rate_limited
                - payment_required
                - transcript_revision_changed
                - needs_rebuild
                - source_changed
                - internal_error
                - unprocessable
            message:
              type: string
          required:
            - code
            - message
      required:
        - error
    BmcRevision:
      type: object
      additionalProperties: false
      required:
        - id
        - number
        - createdAt
        - models
        - entries
        - links
      description: >-
        One immutable Canvas revision. Model and entry identities are unique;
        links must match linkedEntryIds and resolve to entries in the same
        model.
      properties:
        id:
          $ref: '#/components/schemas/BmcId'
        number:
          type: integer
          minimum: 1
        createdAt:
          type: string
          format: date-time
        models:
          type: array
          maxItems: 20
          items:
            $ref: '#/components/schemas/BmcModel'
        entries:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/BmcEntry'
        links:
          type: array
          maxItems: 1000
          items:
            $ref: '#/components/schemas/BmcLink'
        sourceRefs:
          type: array
          maxItems: 30
          items:
            $ref: '#/components/schemas/BmcSourceRef'
    BmcId:
      type: string
      minLength: 1
      maxLength: 200
      description: Opaque identity; knowing an ID does not grant access.
    BmcExtractionState:
      type: object
      additionalProperties: false
      required:
        - source
        - status
        - baseRevisionId
        - error
      properties:
        source:
          $ref: '#/components/schemas/BmcSourceRef'
        status:
          type: string
          enum:
            - pending
            - ready
            - error
        baseRevisionId:
          type:
            - string
            - 'null'
          minLength: 1
          maxLength: 200
        error:
          type:
            - string
            - 'null'
          maxLength: 100
        claimedAt:
          type: string
          format: date-time
        rebuild:
          type: boolean
    BmcModel:
      type: object
      additionalProperties: false
      required:
        - id
        - name
        - description
        - status
      properties:
        id:
          $ref: '#/components/schemas/BmcId'
        name:
          type: string
          minLength: 1
          maxLength: 300
        description:
          type:
            - string
            - 'null'
          maxLength: 3000
        status:
          type: string
          enum:
            - current
            - proposed
    BmcEntry:
      type: object
      additionalProperties: false
      required:
        - id
        - modelId
        - blockId
        - label
        - detail
        - evidenceKind
        - reviewStatus
        - dispute
        - sourceRefs
        - linkedEntryIds
        - hostFields
      description: >-
        An identifiable account within one model. Alternative models retain
        separate identities; unknown blocks may contain no entries.
      properties:
        id:
          $ref: '#/components/schemas/BmcId'
        modelId:
          $ref: '#/components/schemas/BmcId'
        blockId:
          $ref: '#/components/schemas/BmcBlockId'
        label:
          type: string
          minLength: 1
          maxLength: 300
        detail:
          type:
            - string
            - 'null'
          maxLength: 5000
        evidenceKind:
          $ref: '#/components/schemas/BmcEvidenceKind'
        reviewStatus:
          $ref: '#/components/schemas/BmcReviewStatus'
        dispute:
          type:
            - string
            - 'null'
          maxLength: 3000
        sourceRefs:
          type: array
          maxItems: 30
          items:
            $ref: '#/components/schemas/BmcSourceRef'
        linkedEntryIds:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/BmcId'
        hostFields:
          type: array
          maxItems: 7
          description: >-
            Fields protected by explicit human edits; conflicting later
            extraction remains a proposal.
          items:
            type: string
            enum:
              - blockId
              - label
              - detail
              - evidenceKind
              - reviewStatus
              - dispute
              - linkedEntryIds
        hostAuthored:
          type: boolean
          description: >-
            Present on entries added by an editor without invented group-summary
            provenance.
    BmcLink:
      type: object
      additionalProperties: false
      required:
        - fromEntryId
        - toEntryId
      properties:
        fromEntryId:
          $ref: '#/components/schemas/BmcId'
        toEntryId:
          $ref: '#/components/schemas/BmcId'
    BmcSourceRef:
      type: object
      additionalProperties: false
      required:
        - kind
        - stepId
        - stepIndex
        - sessionId
        - summaryDigest
      description: >-
        Group-summary provenance, not an original contribution reference or
        permission to read a private transcript.
      properties:
        kind:
          type: string
          enum:
            - group_summary
        stepId:
          $ref: '#/components/schemas/BmcId'
        stepIndex:
          type: integer
          minimum: 0
        sessionId:
          $ref: '#/components/schemas/BmcId'
        summaryDigest:
          type: string
          pattern: ^[a-f0-9]{64}$
    BmcBlockId:
      type: string
      enum:
        - key_partnerships
        - key_activities
        - key_resources
        - value_propositions
        - customer_relationships
        - channels
        - customer_segments
        - cost_structure
        - revenue_streams
    BmcEvidenceKind:
      type: string
      enum:
        - unknown
        - hypothesis
        - estimate
        - reported
        - observed
      description: >-
        Recorded evidence basis, separate from human confirmation of wording;
        not independent market validation.
    BmcReviewStatus:
      type: string
      enum:
        - proposed
        - confirmed
      description: >-
        Human review of the entry's wording. Confirmation does not change an
        estimate or hypothesis into verified evidence.
  responses:
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds to wait before retrying
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Rate limit exceeded. Try again in 30 seconds.
  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.
    chainParticipantToken:
      type: apiKey
      in: header
      name: x-chain-participant-token
      description: >-
        Signed identity from an existing chain invitation. Only supported by the
        BMC read operation; the server rechecks chain membership, withdrawal,
        round eligibility and participant sharing. It grants no workspace role.

````

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