Skip to main content

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.

The Harmonica API lets you read session data and submit responses programmatically. Use it to build integrations, chatbots, or connect AI agents via MCP.

​
Base URL

https://app.harmonica.chat/api/v1

​
Authentication

All requests require an API key passed as a Bearer token: 
curl https://app.harmonica.chat/api/v1/sessions \
  -H "Authorization: Bearer hm_live_your_key_here"

​
Creating an API key

Generate a key via the API (requires an active browser session): 
curl -X POST https://app.harmonica.chat/api/v1/api-keys \
  -H "Content-Type: application/json" \
  -d '{"name": "My integration"}'
The response includes the full key once — store it securely. You’ll only see the prefix (hm_live_xxxx) after creation.

​
Access scope

Your API key inherits your user permissions. You can access sessions you own or participate in, same as the web UI.

​
Rate limits

API keys are limited to 100 requests per minute. Exceeding this returns 429 Too Many Requests with a Retry-After header.

​
Error format

All errors follow a consistent structure: 
{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}
Error codes: unauthorized, forbidden, not_found, validation_error, rate_limited, internal_error.