# Meliora API

> Meliora public API v1: read campaigns, leads, conversations and the event feed with an organization API key. Read-only, early access.

Base URL: https://api.melioralab.io/v1. Authentication: the `Authorization: Bearer <key>` header. Never pass the key in the URL.

## For agents

- [Full documentation in one file](https://docs.melioralab.io/en/llms-full.txt): guides and API reference in Markdown.
- [OpenAPI 3.1 specification](https://docs.melioralab.io/en/openapi.json): endpoints, parameters and response schemas.
- [AI agent prompt](https://docs.melioralab.io/en/agent-prompt.txt): integration rules for your assistant.

## Guides

- [Meliora API](https://docs.melioralab.io/en/md/index.md): Meliora public API v1: read your organization's campaigns, leads, stored conversations and event feed from your CRM or your own system.
- [Quickstart](https://docs.melioralab.io/en/md/quickstart.md): Make your first Meliora API request in 5 minutes: get a key, check access, list campaigns and leads, and subscribe to the event feed.
- [Authentication and keys](https://docs.melioralab.io/en/md/authentication.md): Meliora API keys: how to get one, read permissions, scope, expiration, IP addresses, rotation, revocation and secure storage.
- [Errors](https://docs.melioralab.io/en/md/errors.md): Meliora API error format (application/problem+json, RFC 9457), error codes, the Request-Id header, and which errors to retry.
- [Pagination](https://docs.melioralab.io/en/md/pagination.md): How to page through Meliora API lists: cursors, the limit parameter, the has_more and next_cursor fields, cursor lifetime and record order.
- [Rate limits and retries](https://docs.melioralab.io/en/md/rate-limits.md): Meliora API rate limits in weight units by plan, the RateLimit headers, handling 429 and 503, and safe retries.
- [Versioning](https://docs.melioralab.io/en/md/versioning.md): How the Meliora API is versioned, which changes count as backward compatible, and how to write a client that survives them.
- [Polling events](https://docs.melioralab.io/en/md/events-polling.md): Reliable polling of the Meliora API event feed: storing the cursor, applying a page atomically, deduplicating by event.id, start=now, the 410 response and recovery after downtime.
- [CRM mapping](https://docs.melioralab.io/en/md/crm-mapping.md): How to match Meliora API leads and events to CRM records with fields.record_id, what record_id_status means, and why a Telegram username doesn't work as a key.
- [Lead and delivery statuses](https://docs.melioralab.io/en/md/lead-states.md): What status, delivery_state, automation_state and reason_code mean in the Meliora API, in plain terms, including values that are not returned yet.
- [AI agents and MCP](https://docs.melioralab.io/en/md/ai-agents.md): How to connect the Meliora API docs to Claude, ChatGPT, Cursor and Claude Code: llms.txt, llms-full.txt, openapi.json, per-page Markdown, a ready-made prompt, and how to handle your key safely.
- [Changelog](https://docs.melioralab.io/en/md/changelog.md): Changes to the Meliora public API by version.
- [What's next](https://docs.melioralab.io/en/md/roadmap.md): Capabilities we're working on for future versions of the Meliora API. No dates.
- [Support](https://docs.melioralab.io/en/md/support.md): How to contact Meliora support about the API and what to include in your request.

## API reference

- [API reference](https://docs.melioralab.io/en/md/reference.md): Meliora API v1 reference: base URL, authentication, data format, routes, response headers and the error object.
- [Reference: Key context](https://docs.melioralab.io/en/md/reference/api-context.md): Which key is making the request, what it can see and which limits apply to it right now.
- [Reference: Workspaces](https://docs.melioralab.io/en/md/reference/workspaces.md): Workspaces are separate areas of your organization. Each has its own campaigns, accounts and contacts.
- [Reference: Campaigns](https://docs.melioralab.io/en/md/reference/campaigns.md): A campaign is a message sequence that Telegram accounts send to contacts on a schedule.
- [Reference: Leads](https://docs.melioralab.io/en/md/reference/leads.md): A lead is one contact taking part in one campaign. If the same person is in two campaigns, that is two leads with different id values.
- [Reference: Conversations](https://docs.melioralab.io/en/md/reference/messages.md): Saved messages of an account's conversation with a lead: outbound sequence steps, manual messages and replies.
- [Reference: Events](https://docs.melioralab.io/en/md/reference/events.md): The event feed: the first message to a lead and the lead's reply. Read it with a cursor to learn about changes without scanning every lead.

## Other languages

- [Russian version](https://docs.melioralab.io/llms.txt)