API reference

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

#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`	Retrieve API key details	any
`GET /v1/workspaces`	List workspaces	any
`GET /v1/campaigns`	List campaigns	`campaigns:read`
`GET /v1/campaigns/{id}`	Retrieve a campaign	`campaigns:read`
`GET /v1/leads`	List leads	`leads:read`
`GET /v1/leads/{id}`	Retrieve a lead	`leads:read`
`GET /v1/leads/{id}/messages`	List lead conversation	`messages:read`
`GET /v1/events`	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.
`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. Errors use the application/problem+json format. The error object is described below, and the codes are listed in Errors.

First request

curl https://api.melioralab.io/v1/me \
  -H "Authorization: Bearer $MELIORA_API_KEY"

const res = await fetch('https://api.melioralab.io/v1/me', {
  headers: { Authorization: `Bearer ${process.env.MELIORA_API_KEY}` },
});
if (!res.ok) throw new Error(`Meliora API: ${res.status}`);
const body = await res.json();

import os
import requests

resp = requests.get(
    "https://api.melioralab.io/v1/me",
    headers={"Authorization": f"Bearer {os.environ['MELIORA_API_KEY']}"},
    timeout=15,
)
resp.raise_for_status()
body = resp.json()

Base URL

https://api.melioralab.io/v1

#The Problem object

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

Attributes

typestring
Error type URI: urn:meliora:problem:<code>.
titlestring
Short error title in English.
statusinteger
HTTP status.
detailstring
Explanation in Russian or English, based on the Accept-Language header. Do not parse this text in code.
instancestring
Request URI: urn:request:<request_id>.
codestring
Machine-readable error code. Handle errors by status and code.
paramstring or null
Parameter the error refers to, or null.
request_idstring (uuid)
Request ID, the same as in the Request-Id header.

Error response

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json; charset=utf-8
Request-Id: 0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20
Cache-Control: no-store

{
  "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"
}