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

# Seed, inspect or rebuild the listening map

> Trigger cross-pollination scratchpad seeding or update for a session.
The scratchpad tracks themes, emerging consensus, open tensions, and
declared-question coverage from currently included conversations.

**Modes:**
- `seed` (default): Process all user messages from scratch. Resumes from
  existing progress if the session was partially seeded.
- `update`: Process only new messages since the last update.
- `status`: Return current scratchpad state without processing.
  Includes `eligibility_digest` for an optimistic rebuild and `needs_rebuild`.
- `rebuild`: Discard the previous map, resume offset and accumulated
  completeness. Requires the current `expectedEligibilityDigest` from status.

Requires editor role. The map is maintained regardless of cross-pollination;
that setting controls injection into participant conversations.
Changing response inclusion invalidates this map and maps seeded from it.
Legacy maps without input receipts and maps whose context sources changed
are withheld until deliberately refreshed. Context source versions are
checked before analysis, publication and use in participant prompts.
An automatic `update` cannot restart that backfill; request an explicit
`seed` or `rebuild`. Stale in-flight writes cannot restore removed input.
Referenced maps must be refreshed first. Session-reference cycles require
removing a reference in the cycle before rebuilding; cyclic reconstruction
is not supported.

For large sessions, seeding may take multiple calls (up to 5 minutes per
call). Each batch is persisted to the database, so partial progress
survives timeouts. Processing stops at the first failed batch so the resume
offset never skips missing evidence. Re-call explicitly to continue.




## OpenAPI

````yaml /api-reference/openapi.yaml post /sessions/{id}/scratchpad
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}/scratchpad:
    post:
      tags:
        - Sessions
      summary: Seed, inspect or rebuild the listening map
      description: >
        Trigger cross-pollination scratchpad seeding or update for a session.

        The scratchpad tracks themes, emerging consensus, open tensions, and

        declared-question coverage from currently included conversations.


        **Modes:**

        - `seed` (default): Process all user messages from scratch. Resumes from
          existing progress if the session was partially seeded.
        - `update`: Process only new messages since the last update.

        - `status`: Return current scratchpad state without processing.
          Includes `eligibility_digest` for an optimistic rebuild and `needs_rebuild`.
        - `rebuild`: Discard the previous map, resume offset and accumulated
          completeness. Requires the current `expectedEligibilityDigest` from status.

        Requires editor role. The map is maintained regardless of
        cross-pollination;

        that setting controls injection into participant conversations.

        Changing response inclusion invalidates this map and maps seeded from
        it.

        Legacy maps without input receipts and maps whose context sources
        changed

        are withheld until deliberately refreshed. Context source versions are

        checked before analysis, publication and use in participant prompts.

        An automatic `update` cannot restart that backfill; request an explicit

        `seed` or `rebuild`. Stale in-flight writes cannot restore removed
        input.

        Referenced maps must be refreshed first. Session-reference cycles
        require

        removing a reference in the cycle before rebuilding; cyclic
        reconstruction

        is not supported.


        For large sessions, seeding may take multiple calls (up to 5 minutes per

        call). Each batch is persisted to the database, so partial progress

        survives timeouts. Processing stops at the first failed batch so the
        resume

        offset never skips missing evidence. Re-call explicitly to continue.
      operationId: seedScratchpad
      parameters:
        - $ref: '#/components/parameters/sessionId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                mode:
                  type: string
                  enum:
                    - seed
                    - update
                    - status
                    - rebuild
                  default: seed
                  description: Processing mode
                expectedEligibilityDigest:
                  type: string
                  description: >-
                    Required for rebuild; use eligibility_digest from a fresh
                    status response
      responses:
        '200':
          description: Scratchpad result
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                      - completed
                      - partial
                      - no_data
                      - busy
                      - exists
                      - empty
                    description: >
                      `completed` — all messages processed.

                      `partial` — a batch failed or processing is incomplete;
                      request continuation explicitly.

                      `no_data` — no user messages in session.

                      `busy` — another writer owns the current analysis claim.

                      `exists`/`empty` — status mode response.
                  themes:
                    type: integer
                    description: Number of themes identified
                  participants:
                    type: integer
                    description: Number of participants tracked
                  batches_processed:
                    type: integer
                    description: Batches completed in this call
                  batches_total:
                    type: integer
                    description: Total batches needed for remaining messages
                  eligibility_digest:
                    type: string
                    description: >-
                      Opaque token identifying the captured conversation input
                      and context inventory; returned in status mode
                  needs_rebuild:
                    type: boolean
                    description: >-
                      Stored map has no verified current input basis and
                      requires deliberate refresh; returned in status mode
                required:
                  - status
                  - themes
                  - participants
        '400':
          description: Invalid JSON request body or unknown processing mode
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error:
                  code: validation_error
                  message: Unknown scratchpad mode
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: >-
            Included evidence changed or an explicit rebuild is required; no
            stale analysis is published
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    sessionId:
      name: id
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Session ID
  schemas:
    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
  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
    Forbidden:
      description: Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: You don't have access to this session
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: not_found
              message: Session not found
  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.