Skip to main content
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.