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

# API Reference

> REST API for programmatic access to Harmonica sessions

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:

```bash theme={null}
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):

```bash theme={null}
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:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Session not found"
  }
}
```

Error codes: `unauthorized`, `forbidden`, `not_found`, `validation_error`, `rate_limited`, `internal_error`.