# Meliora API

Read campaigns, leads, stored conversations and events from your Meliora organization in your CRM or your own system. Version v1, early access.

AI agent prompt: https://docs.melioralab.io/en/agent-prompt.txt

## What you can do

The API returns your organization's data as JSON, authenticated with an organization API key. Common use cases:

- **Sync replies to your CRM.** The event feed tells you when a lead gets the first message and when they reply. The `fields.record_id` field on the lead links it to a CRM record.
- **Track campaign progress.** Campaign and lead states, delivery state and the reason a lead is waiting, such as the sending window or the account's daily quota.
- **Pull conversations.** Stored messages with a lead: sequence steps, manual messages from your managers, and replies.
- **Reconcile data.** Lists of campaigns and leads, filtered by workspace, campaign, status and username.

## Endpoints

Every endpoint in v1 is read-only and uses the GET method.

| Endpoint | Returns | Permission |
|---|---|---|
| [`GET /v1/me`](https://docs.melioralab.io/en/reference/api-context/#getMe) | Retrieve API key details | any |
| [`GET /v1/workspaces`](https://docs.melioralab.io/en/reference/workspaces/#listWorkspaces) | List workspaces | any |
| [`GET /v1/campaigns`](https://docs.melioralab.io/en/reference/campaigns/#listCampaigns) | List campaigns | `campaigns:read` |
| [`GET /v1/campaigns/{id}`](https://docs.melioralab.io/en/reference/campaigns/#getCampaign) | Retrieve a campaign | `campaigns:read` |
| [`GET /v1/leads`](https://docs.melioralab.io/en/reference/leads/#listLeads) | List leads | `leads:read` |
| [`GET /v1/leads/{id}`](https://docs.melioralab.io/en/reference/leads/#getLead) | Retrieve a lead | `leads:read` |
| [`GET /v1/leads/{id}/messages`](https://docs.melioralab.io/en/reference/messages/#listLeadMessages) | List lead conversation | `messages:read` |
| [`GET /v1/events`](https://docs.melioralab.io/en/reference/events/#listEvents) | List events | `events:read` |

## How the API works

- Base URL: `https://api.melioralab.io/v1`.
- Pass the key in the `Authorization: Bearer mel_live_...` header. The key belongs to your organization, not to a team member, so it keeps working if the person who created it leaves.
- Responses are UTF-8 JSON. Field names use `snake_case`, IDs are UUIDs, and timestamps are ISO 8601 in UTC with a `Z` suffix.
- A key sees only what its permissions and scope allow. To the key, an object outside its scope does not exist and returns 404.
- Call the API from your server. Browser requests from third-party sites are not supported.

## Early access

The API is in early access. Keys are issued on request: contact [Support](https://docs.melioralab.io/en/support/), and we will enable API access for your organization and issue a key. Read access is available on the Pro plan and above.

Before you start:

- **Read-only.** You can't import contacts or start or stop a sequence through the API yet. Do this in Meliora instead.
- **The conversation archive may be incomplete.** The API returns what has been stored. `meta.completeness` tells you how complete it is.
- **The feed keeps events for 30 days.** Poll it regularly. After a long outage, reconcile records as described in [Polling events](https://docs.melioralab.io/en/events-polling/).
- **Some status values are not sent yet.** See [Lead and delivery states](https://docs.melioralab.io/en/lead-states/) for details.

## Where to start

1. [Quickstart](https://docs.melioralab.io/en/quickstart/): make your first request in 5 minutes.
2. [Authentication and keys](https://docs.melioralab.io/en/authentication/): permissions, scope, rotation and revocation.
3. [Polling events](https://docs.melioralab.io/en/events-polling/): a reliable polling loop for CRM integrations.
4. [API reference](https://docs.melioralab.io/en/reference/): every field, parameter and example response.
5. [AI agents and MCP](https://docs.melioralab.io/en/ai-agents/): how to give these docs to Claude, ChatGPT, Cursor or Claude Code.

You can download the OpenAPI 3.1 specification: [openapi.json](https://docs.melioralab.io/en/openapi.json). Import it into Postman, Insomnia or a client generator.