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

# Regenerate the stakeholder engagement map

> Requires editor access or above and admission to the results audience
(owner or admin for host-only sessions). Send an empty body or {}.
Extracts reported accounts from included non-preview authored answers,
preserving host-corrected fields. A real summary is required. No answers
means no model call and no map write. A source change during generation
returns 409 without replacing the saved state. Existing sessions are not
backfilled; a future summary or this explicit action generates their map.




## OpenAPI

````yaml /api-reference/openapi.yaml post /sessions/{id}/stakeholders
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}/stakeholders:
    post:
      tags:
        - Sessions
      summary: Regenerate the stakeholder engagement map
      description: >
        Requires editor access or above and admission to the results audience

        (owner or admin for host-only sessions). Send an empty body or {}.

        Extracts reported accounts from included non-preview authored answers,

        preserving host-corrected fields. A real summary is required. No answers

        means no model call and no map write. A source change during generation

        returns 409 without replacing the saved state. Existing sessions are not

        backfilled; a future summary or this explicit action generates their
        map.
      operationId: regenerateStakeholderMap
      parameters:
        - $ref: '#/components/parameters/sessionId'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              additionalProperties: false
              maxProperties: 0
      responses:
        '200':
          description: Regenerated map with authorized editor review fields.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapResponse'
        '400':
          description: >-
            Invalid body, missing real summary or no included participant
            answers.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: Editor role or results-audience access is missing.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapError'
        '404':
          description: >-
            Session absent or not a supported standalone Stakeholder Analysis
            session.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapError'
        '409':
          description: Map source or state changed; reload before regenerating.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapError'
        '500':
          description: The map could not be generated.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakeholderMapError'
components:
  parameters:
    sessionId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Session ID
  schemas:
    StakeholderMapResponse:
      type: object
      additionalProperties: false
      required:
        - artifact
        - canEdit
        - canRegenerate
      properties:
        artifact:
          $ref: '#/components/schemas/StakeholderMapArtifact'
        canEdit:
          type: boolean
        canRegenerate:
          type: boolean
        review:
          type: object
          additionalProperties: false
          description: >-
            Editor-only source/current-state fence for the host correction UI;
            omitted for other readers.
          required:
            - editToken
            - coverage
          properties:
            editToken:
              type: string
              pattern: ^[a-f0-9]{64}$
            coverage:
              type: object
              additionalProperties: false
              required:
                - eligibleMessages
                - extractedMessages
                - sourceFingerprint
              properties:
                eligibleMessages:
                  type: integer
                  minimum: 0
                extractedMessages:
                  type: integer
                  minimum: 0
                sourceFingerprint:
                  type: string
                  pattern: ^[a-f0-9]{64}$
    StakeholderMapError:
      type: object
      additionalProperties: false
      required:
        - error
        - code
      properties:
        error:
          type: string
        code:
          type: string
          enum:
            - not_found
            - host_only
            - participants_only
            - community_gated
            - private_results
            - editor_required
            - summary_required
            - no_participant_answers
            - invalid_request
            - stakeholder_changed
            - internal_error
    StakeholderMapArtifact:
      type: object
      additionalProperties: false
      required:
        - kind
        - schemaVersion
        - title
        - revision
        - generatedAt
        - sourceStatus
        - coverage
        - items
      properties:
        kind:
          type: string
          enum:
            - stakeholder-engagement
        schemaVersion:
          type: integer
          enum:
            - 1
        title:
          type:
            - string
            - 'null'
        revision:
          type: integer
          minimum: 0
        generatedAt:
          type:
            - integer
            - 'null'
          description: >-
            Unix epoch milliseconds of the latest successful extraction; null
            before generation.
        sourceStatus:
          type: string
          enum:
            - current
            - changed
            - not_generated
          description: >-
            Changed source answers withhold public and participant items until
            regeneration. Editors can inspect explicitly flagged saved content.
        coverage:
          type:
            - object
            - 'null'
          additionalProperties: false
          description: >-
            Safe counts from the latest extraction, without source identities or
            fingerprints. Null before generation; partial coverage must not
            imply all perspectives were reviewed.
          required:
            - eligibleMessages
            - extractedMessages
          properties:
            eligibleMessages:
              type: integer
              minimum: 0
            extractedMessages:
              type: integer
              minimum: 0
        items:
          type: array
          items:
            $ref: '#/components/schemas/StakeholderMapEntry'
    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
    StakeholderMapEntry:
      type: object
      additionalProperties: false
      required:
        - id
        - label
        - influence
        - interest
        - stance
        - perspective
        - concerns
        - engagementProposal
        - evidenceCount
        - hostEditedFields
      description: >-
        A reported account, not a verified position or agreed engagement
        decision. Conflicting accounts may share a label.
      properties:
        id:
          type: string
          description: >-
            Opaque native entry identity, not a participant or source-message
            ID.
        label:
          type: string
          maxLength: 300
        influence:
          type:
            - string
            - 'null'
          enum:
            - low
            - medium
            - high
            - null
          description: Null means unknown and remains unplaced.
        interest:
          type:
            - string
            - 'null'
          enum:
            - low
            - medium
            - high
            - null
        stance:
          type: string
          enum:
            - supportive
            - neutral
            - resistant
            - unknown
        perspective:
          type: string
          enum:
            - self_reported
            - reported_by_others
            - unclear
          description: >-
            Describes the recorded account; self_reported does not verify a
            named person's identity.
        concerns:
          type: array
          maxItems: 20
          items:
            type: string
            maxLength: 2000
        engagementProposal:
          type:
            - string
            - 'null'
          maxLength: 4000
          description: >-
            A reported proposal, without assigned responsibility or
            authorization to act.
        evidenceCount:
          type: integer
          minimum: 0
          description: >-
            Current supporting references, not votes. Public and participant
            entries always have at least one; an editor's saved review entry may
            have none.
        hostEditedFields:
          type: array
          items:
            type: string
            enum:
              - label
              - influence
              - interest
              - stance
              - perspective
              - concerns
              - engagementProposal
        sourceStatus:
          type: string
          enum:
            - current
            - needs_review
          description: >-
            Editor-only review status; omitted from public and participant
            responses.
        evidenceQuotes:
          type: array
          description: >-
            Editor-only source excerpts. Never included for public readers,
            community members or participants solely by virtue of that access.
          items:
            type: object
            additionalProperties: false
            required:
              - messageId
              - text
            properties:
              messageId:
                type: string
              text:
                type: string
  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
  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.