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

# Correct, review or control sharing of a Canvas

> Requires authenticated workspace editor access plus each source session's
results audience. Participant tokens do not authorize writes. Changes use
expectedRevision under the chain lock; stale revisions return bmc_changed.
Unknown or duplicate entries, conflicting removals and invalid links are
rejected. Additions use an existing model ID and a server-generated entry ID.
Edits/removals are protected against later extraction; new conflicting model
output remains a proposal. No model call is made by this operation.

approve=true reviews the resulting revision for the next dependent round.
closing=true also requires approve=true, a completed chain and a current
final extraction. Neither action supplies group agreement or validates
estimates. Sharing-only changes can be made before a Canvas exists or when
source content is withheld, using management.expectedRevision and edits=[].
Source-dependent edits/approvals require current sources. Turning sharing
off denies later participant reads, including the closing Canvas; it does
not grant new transcript access. Responses use private, no-store.




## OpenAPI

````yaml /api-reference/openapi.yaml patch /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:
    patch:
      tags:
        - Chains
      summary: Correct, review or control sharing of a Canvas
      description: >
        Requires authenticated workspace editor access plus each source
        session's

        results audience. Participant tokens do not authorize writes. Changes
        use

        expectedRevision under the chain lock; stale revisions return
        bmc_changed.

        Unknown or duplicate entries, conflicting removals and invalid links are

        rejected. Additions use an existing model ID and a server-generated
        entry ID.

        Edits/removals are protected against later extraction; new conflicting
        model

        output remains a proposal. No model call is made by this operation.


        approve=true reviews the resulting revision for the next dependent
        round.

        closing=true also requires approve=true, a completed chain and a current

        final extraction. Neither action supplies group agreement or validates

        estimates. Sharing-only changes can be made before a Canvas exists or
        when

        source content is withheld, using management.expectedRevision and
        edits=[].

        Source-dependent edits/approvals require current sources. Turning
        sharing

        off denies later participant reads, including the closing Canvas; it
        does

        not grant new transcript access. Responses use private, no-store.
      operationId: updateBusinessModelCanvas
      parameters:
        - $ref: '#/components/parameters/chainInstanceId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BmcEditRequest'
            example:
              expectedRevision: 2
              edits:
                - entryId: cost-estimate
                  evidenceKind: estimate
                  reviewStatus: confirmed
                  dispute: Another contributor estimates a higher cost; unresolved.
              approve: true
      responses:
        '200':
          description: Updated management state and preparation/review eligibility.
          headers:
            Cache-Control:
              schema:
                type: string
              description: private, no-store
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcReadResponse'
        '400':
          description: >-
            Invalid update shape or entry edit (validation_error or
            bmc_invalid_edit).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Workspace editor or source-results audience access is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '404':
          description: Chain absent or not a BMC chain.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '409':
          description: >-
            Canvas revision/source changed or closing extraction/review is not
            ready. Refresh before deciding on another update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          description: The Canvas could not be updated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BmcError'
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:
    BmcEditRequest:
      type: object
      additionalProperties: false
      required:
        - expectedRevision
        - edits
      properties:
        expectedRevision:
          type: integer
          minimum: 0
          description: >-
            Latest management.expectedRevision from a read. A stale value
            returns 409; zero permits a sharing-only change before any Canvas
            exists.
        edits:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/BmcHostEntryEdit'
        additions:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/BmcHostEntryAddition'
        removeEntryIds:
          type: array
          maxItems: 500
          items:
            $ref: '#/components/schemas/BmcId'
        approve:
          type: boolean
          description: >-
            Mark the resulting revision reviewed for the next dependent round;
            does not establish participant agreement or market validation.
        closing:
          type: boolean
          description: >-
            Requires approve=true, a completed chain and current final
            extraction; makes the resulting revision the approved closing
            Canvas.
        participantSharingEnabled:
          type: boolean
          description: >-
            Controls participant Canvas reads, including closing access. Send
            edits=[] for a sharing-only change, without generating a model
            revision or model call.
    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
    BmcHostEntryEdit:
      type: object
      additionalProperties: false
      required:
        - entryId
      properties:
        entryId:
          $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
        linkedEntryIds:
          type: array
          maxItems: 100
          items:
            $ref: '#/components/schemas/BmcId'
    BmcHostEntryAddition:
      type: object
      additionalProperties: false
      required:
        - modelId
        - blockId
        - label
        - evidenceKind
      description: >-
        Adds an entry to an existing model with a server-generated entry ID and
        no invented source reference. Defaults to confirmed wording when
        reviewStatus is omitted.
      properties:
        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'
        dispute:
          type:
            - string
            - 'null'
          maxLength: 3000
        reviewStatus:
          $ref: '#/components/schemas/BmcReviewStatus'
    BmcId:
      type: string
      minLength: 1
      maxLength: 200
      description: Opaque identity; knowing an ID does not grant access.
    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
    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.
    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'
    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}$
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Invalid or missing API key
    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.

````

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