# Harmonica - [Welcome to Harmonica](https://help.harmonica.chat/index.md): Conversational survey platform for qualitative insights and group coordination - [Quickstart](https://help.harmonica.chat/quickstart.md): Get started with Harmonica in minutes - [Frequently Asked Questions](https://help.harmonica.chat/faq.md): Common questions about Harmonica - [Data Privacy & Security](https://help.harmonica.chat/privacy.md): How Harmonica handles your data, where it's stored, and your options for control - [Participating in a Session](https://help.harmonica.chat/guides/participants/participating-in-sessions.md): Learn how to join and contribute to Harmonica sessions - [Creating Sessions](https://help.harmonica.chat/guides/hosts/creating-sessions.md): Learn how to create and manage Harmonica sessions - [Session Design](https://help.harmonica.chat/guides/hosts/session-design.md): Edit all four prompt layers that shape how your facilitator runs a session - [Session Results](https://help.harmonica.chat/guides/hosts/session-results.md): Review summaries, responses, and insights from your sessions - [Templates](https://help.harmonica.chat/guides/hosts/templates.md): Use pre-built templates to create sessions quickly - [Chains](https://help.harmonica.chat/guides/hosts/chains.md): Run multi-step session sequences where each step builds on the last - [Polls and ratings](https://help.harmonica.chat/guides/hosts/widgets.md): Enable structured widgets so participants can respond with selections, ratings, and rankings - [Context sources](https://help.harmonica.chat/guides/hosts/context-sources.md): Attach files, prior sessions, and MCP servers so the facilitator stays grounded in your material - [Organizational context](https://help.harmonica.chat/guides/hosts/organizational-context.md): Give every session you create a shared organizational context so the facilitator sounds like you - [Notifications](https://help.harmonica.chat/guides/hosts/notifications.md): Stay on top of chain actions, completed steps, and project invitations from the bell in the top nav - [Session Settings](https://help.harmonica.chat/guides/hosts/session-settings.md): Configure session behavior, sharing, and invitations - [Collaboration](https://help.harmonica.chat/guides/hosts/collaboration.md): Share sessions and projects with your team - [Managing Projects](https://help.harmonica.chat/guides/hosts/managing-projects.md): Organize and manage sessions within projects - [Broad Listening](https://help.harmonica.chat/guides/hosts/broad-listening.md): Publish a project as a public page where anyone can weigh in and see where the group stands - [Bring Your Own Model (BYOM)](https://help.harmonica.chat/guides/hosts/byom.md): Use your own AI API keys to power Harmonica with any supported model - [API Reference](https://help.harmonica.chat/api-reference/introduction.md): REST API for programmatic access to Harmonica sessions - [MCP Server](https://help.harmonica.chat/api-reference/mcp-server.md): Connect AI agents to Harmonica via Model Context Protocol - [Get current user](https://help.harmonica.chat/api-reference/account/get-current-user.md): Returns user info, API key metadata and the private verified ATProto association for the authenticated user. Association storage failures return status unavailable rather than claiming no identity is connected. - [List templates](https://help.harmonica.chat/api-reference/templates/list-templates.md): Returns templates visible to the authenticated user: public global templates, templates they own, and (when `workspace_id` is provided and they have access) that workspace's templates. Archived templates are excluded. - [Create template](https://help.harmonica.chat/api-reference/templates/create-template.md): Creates a template owned by the authenticated user. Private and user-scoped by default; provide `workspace_id` to create a workspace-scoped template (caller must be a workspace admin). - [Get template](https://help.harmonica.chat/api-reference/templates/get-template.md): Returns a single template the caller can read. - [Update template](https://help.harmonica.chat/api-reference/templates/update-template.md): Updates a template. Caller must be the owner, a workspace admin (for workspace-scoped templates), or a global admin. - [Delete template](https://help.harmonica.chat/api-reference/templates/delete-template.md): Deletes a template. Caller must be the owner, a workspace admin (for workspace-scoped templates), or a global admin. - [List projects](https://help.harmonica.chat/api-reference/projects/list-projects.md): List the projects (workspaces) the caller can access. - [Create project](https://help.harmonica.chat/api-reference/projects/create-project.md): Creates an evergreen project (workspace) owned by the authenticated user. Use the returned `id` to publish the project as a public sensemaking topic via `PATCH /projects/{id}/sensemaking`, or reuse an existing project id you already own. - [Get project](https://help.harmonica.chat/api-reference/projects/get-project.md): Get a single project the caller can access, with the ids of its linked sessions. - [Update project](https://help.harmonica.chat/api-reference/projects/update-project.md): Rename a project or update its description. - [Delete project](https://help.harmonica.chat/api-reference/projects/delete-project.md): Soft-deletes a project (sets status to `deleted`). Sessions contained in the project are left intact — only the project record is marked deleted. Requires owner access. - [Attach meeting transcripts to a project in a bounded batch](https://help.harmonica.chat/api-reference/context-sources/attach-meeting-transcripts-to-a-project-in-a-bounded-batch.md): Attach between 1 and 50 owned meetings. Work is processed with bounded concurrency and results retain request order. Every requested item receives an independent outcome, so valid items continue when another item is invalid, unavailable, restricted, over quota, or fails. Repeated meeting IDs and par… - [List owned meetings](https://help.harmonica.chat/api-reference/meetings/list-owned-meetings.md): Lists only personal calendar meetings owned by the API-key user. Project membership never expands this catalogue. Results include compact transcript currentness, processing provenance, safe restriction scopes, and Project attachment counts without transcript text. Provider speaker labels remain unve… - [Get meeting metadata](https://help.harmonica.chat/api-reference/meetings/get-meeting-metadata.md): Returns full metadata to the meeting owner. A named viewer-or-higher member of a non-deleted Project with a current meeting attachment may read redacted metadata. Public and platform-global grants do not confer access. Missing and unauthorized meetings both return 404. Project-derived responses reda… - [Get a bounded transcript page](https://help.harmonica.chat/api-reference/meetings/get-a-bounded-transcript-page.md): Returns one page bounded by both segment count and Unicode code-point text budget. It never auto-follows next_cursor. A cursor is bound to transcript ID and revision and may continue within one oversized speaker turn. If canonical content changes, an old cursor returns 409 transcript_revision_change… - [Export the complete current transcript](https://help.harmonica.chat/api-reference/meetings/export-the-complete-current-transcript.md): Owner-only complete JSON export. The export is intentionally unavailable as an MCP tool, requires a ready canonical transcript, and checks external_export policy immediately before one revision-consistent read. It excludes restriction rationale/history and raw provider artifact identifiers. - [Get meeting processing restrictions](https://help.harmonica.chat/api-reference/meetings/get-meeting-processing-restrictions.md): Returns effective restriction scopes, pending transcript-derived candidates, and append-only provenance for a meeting owned by the authenticated user. - [Update meeting processing restrictions](https://help.harmonica.chat/api-reference/meetings/update-meeting-processing-restrictions.md): Sets the complete authoritative restriction scope or confirms/dismisses a pending transcript-derived candidate. Every mutation appends an event; history is never overwritten. - [Get project sensemaking topic](https://help.harmonica.chat/api-reference/projects/get-project-sensemaking-topic.md): Returns the project's sensemaking topic (publish status, slug, theme, snapshot counts), or `data: null` if it was never published. Editor access required. - [Publish project as sensemaking topic](https://help.harmonica.chat/api-reference/projects/publish-project-as-sensemaking-topic.md): Authors and publishes the project as a public sensemaking topic — the `/explore` hub entry + the `/t/{slug}` page. Send `enabled: true` with a `slug` (in this request or already saved) to publish; publishing builds the public snapshot from the project's sessions. Editor access required. - [Create session](https://help.harmonica.chat/api-reference/sessions/create-session.md): Creates a new deliberation session owned by the authenticated user. If `prompt` is omitted, a facilitation prompt is auto-generated server-side from the topic, goal, context, and critical fields (with a fallback to a basic prompt). Returns the created session with a `join_url` for sharing with parti… - [List sessions](https://help.harmonica.chat/api-reference/sessions/list-sessions.md): Returns sessions the authenticated user has access to (owns or participates in). API keys remain account-scoped by default. A key created by a current global admin with the explicit `platform_sessions:read_metadata` capability may pass `scope=platform` to list platform-wide session metadata. That ca… - [Get session](https://help.harmonica.chat/api-reference/sessions/get-session.md): Returns full details of a session the user has access to. - [Inspect host-authorized chain state and blockers](https://help.harmonica.chat/api-reference/sessions/inspect-host-authorized-chain-state-and-blockers.md): 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 re… - [Request guarded host chain progression](https://help.harmonica.chat/api-reference/sessions/request-guarded-host-chain-progression.md): Requires owner/admin access to the origin session. Platform session metadata audit keys cannot advance chains, even for a session they own. Pass current_step_id from chain-state as expected_step_id. No force, trigger override, credit-retry query option or completion bypass exists in this API-key con… - [Update session](https://help.harmonica.chat/api-reference/sessions/update-session.md): Update session metadata. At least one field must be provided. Requires editor role or higher on the session. - [Close session](https://help.harmonica.chat/api-reference/sessions/close-session.md): Close a session so new participant activity is no longer accepted. Requires editor access or higher. The operation is idempotent and changes only the session's active status; participant threads, messages, summaries, and other session data are preserved. - [Reopen session](https://help.harmonica.chat/api-reference/sessions/reopen-session.md): Reopen a completed session so participants can join or continue again. Requires editor access or higher. The operation is idempotent and changes only the session's active status; existing session data is preserved. - [Get session questions](https://help.harmonica.chat/api-reference/sessions/get-session-questions.md): Returns the facilitation questions/prompts for a session. - [Get session responses](https://help.harmonica.chat/api-reference/sessions/get-session-responses.md): Returns all participant responses for a session, grouped by participant. Each participant's conversation thread includes both user messages and assistant (facilitator) messages. - [Submit a response](https://help.harmonica.chat/api-reference/sessions/submit-a-response.md): Submit a response to an active session as the authenticated user. The session must be active and the user must have at least editor access. - [Get session brief](https://help.harmonica.chat/api-reference/sessions/get-session-brief.md): Returns the structured SESSION.md brief as raw markdown. Auto-generated after summary creation. Returns 404 if not yet generated. - [Get session summary](https://help.harmonica.chat/api-reference/sessions/get-session-summary.md): Returns the AI-generated summary for a completed session. Returns null summary if the session hasn't been summarized yet. - [Generate structured session knowledge](https://help.harmonica.chat/api-reference/sessions/generate-structured-session-knowledge.md): Synthesises typed, structured knowledge from a session — decisions, action items, tensions, and atomic claims — each backed by the message IDs it was drawn from. When the session has grounding enabled, pre-extracted verbatim quotes are resolved to their source messages and woven in as provenance. - [Seed or update scratchpad](https://help.harmonica.chat/api-reference/sessions/seed-or-update-scratchpad.md): Trigger cross-pollination scratchpad seeding or update for a session. The scratchpad tracks themes, emerging consensus, open tensions, and well-covered questions across all participant conversations. - [Send chat message](https://help.harmonica.chat/api-reference/chat/send-chat-message.md): Send a message to a session's AI facilitator as a specific participant. The facilitator responds in a conversational style, guiding the participant through the deliberation topic. When the facilitator considers the conversation complete, `is_final` is set to `true`. - [Submit pre-session answers](https://help.harmonica.chat/api-reference/chat/submit-pre-session-answers.md): Submit answers to a session's pre-session questions and receive the facilitator's opening message. This starts the facilitation for the participant. - [List Telegram groups](https://help.harmonica.chat/api-reference/integrations/list-telegram-groups.md): List Telegram groups registered to the authenticated user's account. - [Register a Telegram group](https://help.harmonica.chat/api-reference/integrations/register-a-telegram-group.md): Register or update a Telegram group on the authenticated user's account. If the group is already registered (same user + group_id), the name and topic_id are updated. Called by the Telegram bot during `/setup`. - [Unregister a Telegram group](https://help.harmonica.chat/api-reference/integrations/unregister-a-telegram-group.md): Remove a Telegram group from the authenticated user's account. ## OpenAPI Specs - [openapi](/api-reference/openapi.yaml) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.