# API reference

Every route, field and response example of the Meliora API v1.

The Meliora API v1 returns your organization's data as JSON. Every route uses the GET method and only reads data. This reference is generated from the [openapi.json](https://docs.melioralab.io/en/openapi.json) specification.

## Base URL

All paths in this reference are relative to `https://api.melioralab.io`. Send requests over HTTPS from your server.

## Authentication

Pass your organization's API key in the `Authorization: Bearer mel_live_...` header. Key permissions and scope are described in [Authentication and keys](https://docs.melioralab.io/en/authentication/).

## Data format

- JSON in UTF-8, with field names in `snake_case`.
- IDs are UUIDs. Message IDs and cursors are opaque strings.
- Timestamps are ISO 8601 in UTC with milliseconds and a `Z` suffix: `2026-10-26T07:30:00.000Z`.
- Every object has an `object` field with its type.
- An unknown value comes back as `unknown` or `null`. The field is never omitted.

## Routes

| 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` |

## Response headers

| Header | Description |
|---|---|
| `Request-Id` | The request UUID. Present on every response, including errors. |
| `Cache-Control` | Always `no-store`: responses are not cached. |
| `RateLimit-Policy`, `RateLimit` | Limit windows and remaining amounts. See [Rate limits and retries](https://docs.melioralab.io/en/rate-limits/#zagolovki). |
| `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` | The limit, remaining amount and time until reset for the window closest to running out. |
| `Retry-After` | Seconds to wait before retrying. Only on 429 and 503 responses. |

## Lists and errors

Lists come back in pages with a cursor. See [Pagination](https://docs.melioralab.io/en/pagination/). Errors use the `application/problem+json` format. The error object is described below, and the codes are listed in [Errors](https://docs.melioralab.io/en/errors/).

## The Problem object

An error in RFC 9457 format (`application/problem+json`).

| Field | Type | Description |
|---|---|---|
| `type` | string | Error type URI: `urn:meliora:problem:<code>`. |
| `title` | string | Short error title in English. |
| `status` | integer | HTTP status. |
| `detail` | string | Explanation in Russian or English, based on the `Accept-Language` header. Do not parse this text in code. |
| `instance` | string | Request URI: `urn:request:<request_id>`. |
| `code` | string | Machine-readable error code. Handle errors by `status` and `code`. |
| `param` | string or null | Parameter the error refers to, or `null`. |
| `request_id` | string (uuid) | Request ID, the same as in the `Request-Id` header. |

```json
{
  "type": "urn:meliora:problem:invalid_parameter",
  "title": "Invalid parameter",
  "status": 400,
  "detail": "Check the parameter value",
  "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20",
  "code": "invalid_parameter",
  "param": "limit",
  "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20"
}
```