{ "openapi": "3.1.0", "info": { "title": "Meliora API", "version": "v1", "summary": "Read Meliora campaigns, leads, conversations and events.", "description": "Meliora public API, version v1. Early access: read-only, with an organization key. Documentation: https://docs.melioralab.io/en", "contact": { "name": "Meliora support", "url": "https://t.me/meliora_support" } }, "servers": [ { "url": "https://api.melioralab.io/v1", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Key context", "description": "Check the key and its settings." }, { "name": "Workspaces", "description": "Workspaces of the organization." }, { "name": "Campaigns", "description": "Message sequences." }, { "name": "Leads", "description": "Contacts' participation in campaigns." }, { "name": "Conversations", "description": "Saved messages with a lead." }, { "name": "Events", "description": "Event feed for polling." } ], "paths": { "/me": { "get": { "operationId": "getMe", "tags": [ "Key context" ], "summary": "Retrieve API key details", "description": "Returns the organization, permissions, scope and limits of the key. Use it as the first request to check the connection. Available to a key with any set of permissions.", "x-permission": null, "x-weight": 1, "parameters": [], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiContext" }, "examples": { "default": { "summary": "Response", "value": { "object": "api_context", "key_id": "9b1e7c42-5a6d-4f83-9e0b-2d7c4a8f1e65", "organization": { "id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17", "name": "Example" }, "scopes": [ "campaigns:read", "events:read", "leads:read", "messages:read" ], "scope": { "workspace_mode": "all", "workspace_ids": [], "workspace_include_future": true, "campaign_mode": "all", "campaign_ids": [], "campaign_include_future": true, "scope_version": 1 }, "api_version": "v1", "expires_at": null, "limits": { "key_second": 5, "key_minute": 300, "org_second": 10, "org_minute": 600, "key_concurrent": 5, "org_concurrent": 10, "max_response_bytes": 1048576, "mode": "normal" }, "collection": { "state": "running", "enabled_at": "2026-10-20T08:00:00.000Z", "pause_pending": false } } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "tags": [ "Workspaces" ], "summary": "List workspaces", "description": "Workspaces in the key's scope, oldest first. Available to a key with any set of permissions.", "x-permission": null, "x-weight": 1, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value from the previous response. Other filters must match the first request.", "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspaceList" }, "examples": { "default": { "summary": "Response", "value": { "object": "list", "data": [ { "object": "workspace", "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Main workspace", "created_at": "2026-09-01T12:00:00.000Z" }, { "object": "workspace", "id": "7a2c5e81-3d9f-4b6a-8c40-1e5f7a9b2d68", "name": "Test outreach", "created_at": "2026-10-02T09:30:00.000Z" } ], "has_more": false, "next_cursor": null } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`, `cursor_mismatch`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter", "cursor_mismatch" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "410": { "description": "Error: `cursor_expired`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:cursor_expired", "title": "Cursor expired", "status": 410, "detail": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "cursor_expired", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "cursor_expired" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/campaigns": { "get": { "operationId": "listCampaigns", "tags": [ "Campaigns" ], "summary": "List campaigns", "description": "Campaigns in the key's scope, oldest first by `created_at`.", "x-permission": "campaigns:read", "x-weight": 2, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value from the previous response. Other filters must match the first request.", "schema": { "type": "string", "maxLength": 8192 } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Only objects in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "status", "in": "query", "required": false, "description": "Only campaigns with this status.", "schema": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "archived", "launching", "failed", "paused_no_credits", "unknown" ] } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignList" }, "examples": { "default": { "summary": "Response", "value": { "object": "list", "data": [ { "object": "campaign", "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Example campaign", "status": "active", "first_message_mode": "template", "accepts_api_leads": false, "reason": { "reason_code": "none", "reason_observed_at": null, "next_attempt_at": null, "requires_customer_action": null }, "created_at": "2026-10-20T08:00:00.000Z", "observed_at": "2026-10-27T09:15:42.000Z" }, { "object": "campaign", "id": "6e3a9c15-2b7d-4f80-9a64-3c1d8e5f7b29", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Follow-up", "status": "paused", "first_message_mode": "template", "accepts_api_leads": false, "reason": { "reason_code": "campaign_paused", "reason_observed_at": "2026-10-25T16:40:00.000Z", "next_attempt_at": null, "requires_customer_action": true }, "created_at": "2026-10-22T11:15:00.000Z", "observed_at": "2026-10-27T09:15:42.000Z" } ], "has_more": true, "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU" } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`, `cursor_mismatch`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter", "cursor_mismatch" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "410": { "description": "Error: `cursor_expired`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:cursor_expired", "title": "Cursor expired", "status": 410, "detail": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "cursor_expired", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "cursor_expired" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/campaigns/{id}": { "get": { "operationId": "getCampaign", "tags": [ "Campaigns" ], "summary": "Retrieve a campaign", "description": "A single campaign by ID. A campaign outside the key's scope returns 404, as if it did not exist.", "x-permission": "campaigns:read", "x-weight": 1, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Campaign ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Campaign" }, "examples": { "default": { "summary": "Response", "value": { "object": "campaign", "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Example campaign", "status": "active", "first_message_mode": "template", "accepts_api_leads": false, "reason": { "reason_code": "none", "reason_observed_at": null, "next_attempt_at": null, "requires_customer_action": null }, "created_at": "2026-10-20T08:00:00.000Z", "observed_at": "2026-10-27T09:15:42.000Z" } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/leads": { "get": { "operationId": "listLeads", "tags": [ "Leads" ], "summary": "List leads", "description": "Leads (contacts' participation in campaigns) in the key's scope, oldest first by `created_at`.", "x-permission": "leads:read", "x-weight": 2, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value from the previous response. Other filters must match the first request.", "schema": { "type": "string", "maxLength": 8192 } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Only objects in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only objects in this campaign.", "schema": { "type": "string", "format": "uuid" } }, { "name": "username", "in": "query", "required": false, "description": "Exact Telegram username. A leading `@` and letter case are ignored.", "schema": { "type": "string", "pattern": "^@?[A-Za-z0-9_]{1,32}$" } }, { "name": "status", "in": "query", "required": false, "description": "Only leads with this status.", "schema": { "type": "string", "enum": [ "new", "contacted", "completed", "replied", "blocked", "failed", "suspended", "deleted", "opted_out", "unknown" ] } }, { "name": "delivery_state", "in": "query", "required": false, "description": "Only leads with this delivery state. The values `waiting_queue` and `failed` are not returned at the moment, so filtering by them returns an empty list.", "schema": { "type": "string", "enum": [ "waiting_queue", "queued", "held", "sent", "failed", "unknown" ] } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" }, "examples": { "default": { "summary": "Response", "value": { "object": "list", "data": [ { "object": "lead", "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "username": "example_user", "status": "replied", "external_id": null, "fields": { "record_id": "crm-10482", "first_name": "Anna", "company": "Example Ltd", "position": "Head of sales", "utm_source": "partner" }, "fields_truncated": false, "record_id_status": "valid", "first_contact_account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": "2026-10-26T07:30:00.000Z", "first_reply_at": "2026-10-26T09:12:00.000Z", "delivery_state": "sent", "automation_state": "unknown", "reason": { "reason_code": "none", "reason_observed_at": null, "next_attempt_at": null, "requires_customer_action": null }, "created_at": "2026-10-25T14:00:00.000Z", "observed_at": "2026-10-27T09:15:42.000Z" }, { "object": "lead", "id": "8c1e5a37-9d2f-4b74-a6e8-2f9b3c7d5a40", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "username": "sample_contact", "status": "contacted", "external_id": null, "fields": { "record_id": null, "first_name": "Igor" }, "fields_truncated": false, "record_id_status": "missing", "first_contact_account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": "2026-10-26T07:42:00.000Z", "first_reply_at": null, "delivery_state": "queued", "automation_state": "running", "reason": { "reason_code": "queue_pending", "reason_observed_at": "2026-10-27T08:58:10.000Z", "next_attempt_at": "2026-10-27T10:00:00.000Z", "requires_customer_action": false }, "created_at": "2026-10-25T14:00:01.000Z", "observed_at": "2026-10-27T09:15:42.000Z" } ], "has_more": true, "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU" } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`, `cursor_mismatch`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter", "cursor_mismatch" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "410": { "description": "Error: `cursor_expired`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:cursor_expired", "title": "Cursor expired", "status": 410, "detail": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "cursor_expired", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "cursor_expired" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/leads/{id}": { "get": { "operationId": "getLead", "tags": [ "Leads" ], "summary": "Retrieve a lead", "description": "A single lead by ID. A lead outside the key's scope returns 404.", "x-permission": "leads:read", "x-weight": 1, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead ID.", "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Lead" }, "examples": { "default": { "summary": "Response", "value": { "object": "lead", "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "workspace_id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "campaign_id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "username": "example_user", "status": "replied", "external_id": null, "fields": { "record_id": "crm-10482", "first_name": "Anna", "company": "Example Ltd", "position": "Head of sales", "utm_source": "partner" }, "fields_truncated": false, "record_id_status": "valid", "first_contact_account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": "2026-10-26T07:30:00.000Z", "first_reply_at": "2026-10-26T09:12:00.000Z", "delivery_state": "sent", "automation_state": "unknown", "reason": { "reason_code": "none", "reason_observed_at": null, "next_attempt_at": null, "requires_customer_action": null }, "created_at": "2026-10-25T14:00:00.000Z", "observed_at": "2026-10-27T09:15:42.000Z" } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/leads/{id}/messages": { "get": { "operationId": "listLeadMessages", "tags": [ "Conversations" ], "summary": "List lead conversation", "description": "Saved messages of the conversation with a lead, oldest first. Requires the `messages:read` permission and \"Message text\" enabled on the key. The archive may be incomplete: see `meta.completeness`.", "x-permission": "messages:read", "x-weight": 3, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Lead ID.", "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value from the previous response. Other filters must match the first request.", "schema": { "type": "string", "maxLength": 8192 } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MessageList" }, "examples": { "default": { "summary": "Response", "value": { "object": "list", "data": [ { "object": "message", "id": "m_6b2e9f403a7c4d158e921c5a7f3b9d08", "direction": "outbound", "author": "campaign", "sent_at": "2026-10-26T07:30:00.000Z", "state": "sent", "media_kind": "none", "text": "Good afternoon, Anna! I'm writing from Example: could you tell me who handles outreach at your company?", "text_truncated": false, "text_unavailable": false, "text_unavailable_reason": null }, { "object": "message", "id": "m_c7a1d3e59b2f4a68b4d05e8f2a6c1b97", "direction": "inbound", "author": "lead", "sent_at": "2026-10-26T09:12:00.000Z", "state": "received", "media_kind": "none", "text": "Hello! That's me, let's have a call tomorrow.", "text_truncated": null, "text_unavailable": false, "text_unavailable_reason": null }, { "object": "message", "id": "m_a3f8c6e27d1b4e949c058b2d4f7a6e13", "direction": "inbound", "author": "lead", "sent_at": "2026-10-26T09:13:30.000Z", "state": "received", "media_kind": "photo", "text": null, "text_truncated": null, "text_unavailable": true, "text_unavailable_reason": "not_saved" } ], "has_more": false, "next_cursor": null, "meta": { "completeness": { "overall": "partial", "inbound": "partial", "outbound": "unknown", "available_from": "2026-10-26T07:30:00.000Z", "available_to": "2026-10-27T09:15:42.000Z", "observed_at": "2026-10-27T09:15:42.000Z" } } } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`, `cursor_mismatch`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter", "cursor_mismatch" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "410": { "description": "Error: `cursor_expired`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:cursor_expired", "title": "Cursor expired", "status": 410, "detail": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "cursor_expired", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "cursor_expired" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } }, "/events": { "get": { "operationId": "listEvents", "tags": [ "Events" ], "summary": "List events", "description": "Events in the order they occur: the first message to a lead and the lead's reply. Poll the feed with the cursor. `next_cursor` is always present, even on an empty page. With `include_text=true` the request weight is 3.", "x-permission": "events:read", "x-weight": 2, "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Number of objects to return per page.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "required": false, "description": "The `next_cursor` value from the previous response. Other filters must match the first request.", "schema": { "type": "string", "maxLength": 8192 } }, { "name": "workspace_id", "in": "query", "required": false, "description": "Only objects in this workspace.", "schema": { "type": "string", "format": "uuid" } }, { "name": "campaign_id", "in": "query", "required": false, "description": "Only objects in this campaign.", "schema": { "type": "string", "format": "uuid" } }, { "name": "type", "in": "query", "required": false, "description": "Only events of this type.", "schema": { "type": "string", "enum": [ "lead.first_message_sent", "lead.replied" ] } }, { "name": "include_text", "in": "query", "required": false, "description": "Include message texts in events. Requires the `messages:read` permission and \"Message text\" enabled on the key.", "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false" } }, { "name": "start", "in": "query", "required": false, "description": "`now`: start the feed from the current moment. Returns an empty page and a cursor. Cannot be combined with `cursor`.", "schema": { "type": "string", "enum": [ "now" ] } } ], "responses": { "200": { "description": "Successful response.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "RateLimit-Policy": { "description": "Rate limit windows in weight units, for example `\"key_second\";q=5;w=1`.", "schema": { "type": "string" } }, "RateLimit": { "description": "Remaining budget and time to reset for each window, for example `\"key_second\";r=4;t=1`.", "schema": { "type": "string" } }, "RateLimit-Limit": { "description": "Limit of the window closest to exhaustion.", "schema": { "type": "integer" } }, "RateLimit-Remaining": { "description": "Remaining budget in this window.", "schema": { "type": "integer" } }, "RateLimit-Reset": { "description": "Seconds until this window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventList" }, "examples": { "default": { "summary": "Response", "value": { "object": "list", "data": [ { "object": "event", "id": "evt_3b9e2c7a1f4d4e8a9b6c0d2e5f7a8c91", "type": "lead.first_message_sent", "api_version": "2026-10-18", "timestamp": "2026-10-26T07:30:00.000Z", "test": false, "data": { "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17", "workspace": { "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Main workspace" }, "campaign": { "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "name": "Example campaign" }, "lead": { "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "username": "example_user", "status": "contacted", "fields": { "record_id": null, "first_name": "Anna", "company": "Example Ltd" }, "fields_truncated": false, "record_id_status": "unknown" }, "account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": "2026-10-26T07:30:00.000Z" } }, { "object": "event", "id": "evt_8d4f1a6c2e9b4c7d8a3e5f0b1c6d9e27", "type": "lead.replied", "api_version": "2026-10-18", "timestamp": "2026-10-26T09:12:00.000Z", "test": false, "data": { "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17", "workspace": { "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Main workspace" }, "campaign": { "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "name": "Example campaign" }, "lead": { "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "username": "example_user", "status": "replied", "fields": { "record_id": null, "first_name": "Anna", "company": "Example Ltd" }, "fields_truncated": false, "record_id_status": "unknown" }, "account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": null, "reply": { "id": "e4b7a2d9-6c1f-4e38-9a5b-0d8c3f7e1a62", "replied_at": "2026-10-26T09:12:00.000Z", "automation_stopped": null } } } ], "has_more": false, "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU", "meta": { "available_from": "2026-10-20T08:00:00.000Z", "retention_days": 30, "collection": { "state": "running", "enabled_at": "2026-10-20T08:00:00.000Z", "pause_pending": false }, "coverage": { "status": "unknown", "gaps": [], "gaps_truncated": false, "incomplete_from": null }, "observed_at": "2026-10-27T09:15:42.000Z" } } }, "with_text": { "summary": "With include_text=true", "value": { "object": "list", "data": [ { "object": "event", "id": "evt_3b9e2c7a1f4d4e8a9b6c0d2e5f7a8c91", "type": "lead.first_message_sent", "api_version": "2026-10-18", "timestamp": "2026-10-26T07:30:00.000Z", "test": false, "data": { "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17", "workspace": { "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Main workspace" }, "campaign": { "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "name": "Example campaign" }, "lead": { "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "username": "example_user", "status": "contacted", "fields": { "record_id": null, "first_name": "Anna", "company": "Example Ltd" }, "fields_truncated": false, "record_id_status": "unknown" }, "account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": "2026-10-26T07:30:00.000Z", "first_message": { "text": "Good afternoon, Anna! I'm writing from Example: could you tell me who handles outreach at your company?", "text_truncated": false, "text_unavailable": false, "text_unavailable_reason": null } } }, { "object": "event", "id": "evt_8d4f1a6c2e9b4c7d8a3e5f0b1c6d9e27", "type": "lead.replied", "api_version": "2026-10-18", "timestamp": "2026-10-26T09:12:00.000Z", "test": false, "data": { "organization_id": "2c8f4a61-7d3e-4b9a-8f21-6a0d5e9c3b17", "workspace": { "id": "3f6a9d21-8b4c-4e7f-a102-5c9e8d7b6a43", "name": "Main workspace" }, "campaign": { "id": "4d8b2f73-6e1a-4c95-b7d0-8a3f5e2c9b14", "name": "Example campaign" }, "lead": { "id": "5a7c3e92-1f4b-4d68-9c2e-7b0a6d4f8e31", "username": "example_user", "status": "replied", "fields": { "record_id": null, "first_name": "Anna", "company": "Example Ltd" }, "fields_truncated": false, "record_id_status": "unknown" }, "account": { "id": "1d9f6b28-4c3e-4a75-8b19-5e7a2c0f6d83", "username": "example_sender", "name": "Mary from Example" }, "first_message_sent_at": null, "reply": { "id": "e4b7a2d9-6c1f-4e38-9a5b-0d8c3f7e1a62", "replied_at": "2026-10-26T09:12:00.000Z", "automation_stopped": null, "text": "Hello! That's me, let's have a call tomorrow.", "text_truncated": null, "text_unavailable": false, "text_unavailable_reason": null } } } ], "has_more": false, "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU", "meta": { "available_from": "2026-10-20T08:00:00.000Z", "retention_days": 30, "collection": { "state": "running", "enabled_at": "2026-10-20T08:00:00.000Z", "pause_pending": false }, "coverage": { "status": "unknown", "gaps": [], "gaps_truncated": false, "incomplete_from": null }, "observed_at": "2026-10-27T09:15:42.000Z" } } }, "start_now": { "summary": "With start=now", "value": { "object": "list", "data": [], "has_more": false, "next_cursor": "v1.k1.Qm9hcmRfMWZ4.c3RyaWN0bHlfb3BhcXVl.dGFnX2V4YW1wbGU.bWFjX2V4YW1wbGVfdmFsdWU", "meta": { "available_from": "2026-10-20T08:00:00.000Z", "retention_days": 30, "collection": { "state": "running", "enabled_at": "2026-10-20T08:00:00.000Z", "pause_pending": false }, "coverage": { "status": "unknown", "gaps": [], "gaps_truncated": false, "incomplete_from": null }, "observed_at": "2026-10-27T09:15:42.000Z" } } } } } } }, "400": { "description": "Error: `invalid_parameter`, `unknown_parameter`, `cursor_mismatch`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "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" } } }, "x-error-codes": [ "invalid_parameter", "unknown_parameter", "cursor_mismatch" ] }, "401": { "description": "Error: `invalid_api_key`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:invalid_api_key", "title": "Invalid API key", "status": 401, "detail": "Provide a valid Bearer API key", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "invalid_api_key", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "invalid_api_key" ] }, "403": { "description": "Error: `scope_required`, `api_disabled`, `api_not_available`, `subscription_inactive`, `module_not_available`, `organization_suspended`, `ip_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:scope_required", "title": "Scope required", "status": 403, "detail": "The API key does not permit this read", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "scope_required", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "scope_required", "api_disabled", "api_not_available", "subscription_inactive", "module_not_available", "organization_suspended", "ip_not_allowed" ] }, "404": { "description": "Error: `not_found`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:not_found", "title": "Not found", "status": 404, "detail": "Not found", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "not_found", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "not_found" ] }, "405": { "description": "Error: `method_not_allowed`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:method_not_allowed", "title": "Method not allowed", "status": 405, "detail": "Method not allowed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "method_not_allowed", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "method_not_allowed" ] }, "410": { "description": "Error: `cursor_expired`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:cursor_expired", "title": "Cursor expired", "status": 410, "detail": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "cursor_expired", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "cursor_expired" ] }, "429": { "description": "Error: `rate_limit_exceeded`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:rate_limit_exceeded", "title": "Rate limit exceeded", "status": 429, "detail": "Request budget exceeded. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "rate_limit_exceeded", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "rate_limit_exceeded" ] }, "503": { "description": "Error: `service_unavailable`, `server_busy`, `integration_initializing`.", "headers": { "Request-Id": { "description": "Request ID. Store it in your logs and include it when you contact support.", "schema": { "type": "string", "format": "uuid" } }, "Retry-After": { "description": "Number of seconds to wait before retrying the request. Sent with 429 and 503 responses.", "schema": { "type": "integer" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" }, "example": { "type": "urn:meliora:problem:service_unavailable", "title": "Service unavailable", "status": 503, "detail": "Data could not be read. Retry later", "instance": "urn:request:0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20", "code": "service_unavailable", "param": null, "request_id": "0f3c7a95-2e8b-4d16-b9a4-6c5e1d8f7b20" } } }, "x-error-codes": [ "service_unavailable", "server_busy", "integration_initializing" ] } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "mel_live_<32 characters>", "description": "Organization key in the `Authorization: Bearer mel_live_...` header." } }, "schemas": { "ApiContext": { "type": "object", "properties": { "object": { "const": "api_context", "description": "Object type, always `api_context`." }, "key_id": { "type": "string", "format": "uuid", "description": "Key ID. The key secret is never returned in responses." }, "organization": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Organization ID." }, "name": { "type": "string", "description": "Organization name." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "The organization on whose behalf the key acts." }, "scopes": { "type": "array", "items": { "type": "string", "enum": [ "campaigns:read", "leads:read", "messages:read", "events:read" ] }, "maxItems": 4, "description": "Read permissions granted to the key." }, "scope": { "$ref": "#/components/schemas/Scope", "description": "Key scope: which workspaces and campaigns it can see." }, "api_version": { "const": "v1", "description": "API version, always `v1`." }, "expires_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the key expires. `null` if no expiry is set." }, "limits": { "$ref": "#/components/schemas/Limits", "description": "Rate limits currently applied to the key." }, "collection": { "$ref": "#/components/schemas/Collection", "description": "Status of saved conversation collection for the API." } }, "required": [ "object", "key_id", "organization", "scopes", "scope", "api_version", "expires_at", "limits", "collection" ], "additionalProperties": false, "description": "Details of the key used for the request: organization, permissions, scope, limits and collection status." }, "Scope": { "type": "object", "properties": { "workspace_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "`all`: all workspaces of the organization; `selected`: only the listed ones." }, "workspace_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 50, "description": "Selected workspaces. An empty array when `workspace_mode=all`." }, "workspace_include_future": { "type": "boolean", "description": "Whether workspaces created after the key was issued are included in the scope." }, "campaign_mode": { "type": "string", "enum": [ "all", "selected" ], "description": "`all`: all campaigns in the selected workspaces; `selected`: only the listed ones." }, "campaign_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "maxItems": 500, "description": "Selected campaigns. An empty array when `campaign_mode=all`." }, "campaign_include_future": { "type": "boolean", "description": "Whether campaigns created after the key was issued are included in the scope." }, "scope_version": { "type": "integer", "minimum": 1, "description": "Scope version number. Increases with every change to the key's scope or permissions." } }, "required": [ "workspace_mode", "workspace_ids", "workspace_include_future", "campaign_mode", "campaign_ids", "campaign_include_future", "scope_version" ], "additionalProperties": false, "description": "Key scope. Workspaces and campaigns outside the scope do not exist for the key: requests for them return 404." }, "Limits": { "type": "object", "properties": { "key_second": { "type": "integer", "minimum": 0, "description": "Weight units per second per key." }, "key_minute": { "type": "integer", "minimum": 0, "description": "Weight units per minute per key." }, "org_second": { "type": "integer", "minimum": 0, "description": "Weight units per second per organization, across all keys combined." }, "org_minute": { "type": "integer", "minimum": 0, "description": "Weight units per minute per organization, across all keys combined." }, "key_concurrent": { "type": "integer", "minimum": 0, "description": "Concurrent requests per key." }, "org_concurrent": { "type": "integer", "minimum": 0, "description": "Concurrent requests per organization." }, "max_response_bytes": { "const": 1048576, "description": "Maximum response size in bytes (1 MiB). Long pages are shortened, no data is lost." }, "mode": { "type": "string", "enum": [ "normal", "emergency" ], "description": "`normal`: normal mode; `emergency`: temporarily reduced limits." } }, "required": [ "key_second", "key_minute", "org_second", "org_minute", "key_concurrent", "org_concurrent", "max_response_bytes", "mode" ], "additionalProperties": false, "description": "Limits in weight units. Request weights are described in the \"Rate limits and retries\" guide." }, "Collection": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "running", "paused", "preparing", "degraded" ], "description": "`running`: collection is active; `paused`: paused in Meliora; `preparing`: preparing after being enabled; `degraded`: data may be incomplete." }, "enabled_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When collection was enabled. `null` if it has not been enabled yet." }, "pause_pending": { "type": "boolean", "description": "A pause or resume was requested in Meliora but has not been applied yet." } }, "required": [ "state", "enabled_at", "pause_pending" ], "additionalProperties": false, "description": "Status of saved conversation collection for the API." }, "Workspace": { "type": "object", "properties": { "object": { "const": "workspace", "description": "Object type, always `workspace`." }, "id": { "type": "string", "format": "uuid", "description": "Workspace ID." }, "name": { "type": "string", "description": "Workspace name." }, "created_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the workspace was created. Can be `null` for older workspaces." } }, "required": [ "object", "id", "name", "created_at" ], "additionalProperties": false, "description": "Workspace: a separate area of the organization with its own campaigns." }, "Campaign": { "type": "object", "properties": { "object": { "const": "campaign", "description": "Object type, always `campaign`." }, "id": { "type": "string", "format": "uuid", "description": "Campaign ID." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Workspace the campaign belongs to." }, "name": { "type": "string", "description": "Campaign name." }, "status": { "type": "string", "enum": [ "draft", "scheduled", "active", "paused", "stopped", "completed", "archived", "launching", "failed", "paused_no_credits", "unknown" ], "description": "Campaign status. An unknown value is returned as `unknown`." }, "first_message_mode": { "const": "template", "description": "Where the first message comes from. Always `template` in v1: from the campaign template." }, "accepts_api_leads": { "const": false, "description": "Whether the campaign accepts contacts through the API. Always `false` in v1." }, "reason": { "$ref": "#/components/schemas/Reason", "description": "Why the campaign is not sending messages right now, if known." }, "created_at": { "type": "string", "format": "date-time", "description": "When the campaign was created." }, "observed_at": { "type": "string", "format": "date-time", "description": "Time the server read the data." } }, "required": [ "object", "id", "workspace_id", "name", "status", "first_message_mode", "accepts_api_leads", "reason", "created_at", "observed_at" ], "additionalProperties": false, "description": "Campaign: a sequence of messages that Telegram accounts send to contacts." }, "Reason": { "type": "object", "properties": { "reason_code": { "type": "string", "enum": [ "none", "schedule_window", "daily_limit", "queue_pending", "telegram_wait", "account_unavailable", "account_restricted", "campaign_paused", "subscription_inactive", "manual_hold", "automation_stopped", "service_unavailable", "unknown" ], "description": "Reason code." }, "reason_observed_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the reason was recorded. `null` if unknown." }, "next_attempt_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the next attempt is expected. `null` if the time is unknown." }, "requires_customer_action": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether someone needs to act in Meliora for sending to resume. `null` if unknown." } }, "required": [ "reason_code", "reason_observed_at", "next_attempt_at", "requires_customer_action" ], "additionalProperties": false, "description": "Waiting reason. Values are described in the \"Lead and delivery states\" guide." }, "Lead": { "type": "object", "properties": { "object": { "const": "lead", "description": "Object type, always `lead`." }, "id": { "type": "string", "format": "uuid", "description": "Lead ID (participation in a campaign)." }, "workspace_id": { "type": "string", "format": "uuid", "description": "Workspace of the campaign." }, "campaign_id": { "type": "string", "format": "uuid", "description": "Campaign the contact participates in." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Telegram username without `@`. Can be `null`. Not unique: use `fields.record_id` to link to your CRM." }, "status": { "type": "string", "enum": [ "new", "contacted", "completed", "replied", "blocked", "failed", "suspended", "deleted", "opted_out", "unknown" ], "description": "Lead status in the campaign." }, "external_id": { "const": null, "description": "Reserved for future versions. Always `null` in v1." }, "fields": { "$ref": "#/components/schemas/Fields", "description": "Allowed fields from the contact record." }, "fields_truncated": { "type": "boolean", "description": "`true` if some field values were shortened or hidden due to size limits." }, "record_id_status": { "type": "string", "enum": [ "valid", "missing", "conflict", "unknown" ], "description": "How reliable `fields.record_id` is: `valid`, `missing`, `conflict` or `unknown`." }, "first_contact_account": { "anyOf": [ { "$ref": "#/components/schemas/Account" }, { "type": "null" } ], "description": "Account that sent the first message. `null` if unknown." }, "first_message_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the first message was sent. `null` if sending is not confirmed." }, "first_reply_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the first reply arrived. `null` if there was no reply." }, "delivery_state": { "type": "string", "enum": [ "waiting_queue", "queued", "held", "sent", "failed", "unknown" ], "description": "Delivery state of the next or most recent message in the sequence." }, "automation_state": { "type": "string", "enum": [ "running", "paused", "held", "stopped", "completed", "unknown" ], "description": "State of the automatic sequence for this lead. Leads without a scheduled message, such as those who replied, currently often have `unknown`." }, "reason": { "$ref": "#/components/schemas/Reason", "description": "Why the sequence is waiting, if known." }, "created_at": { "type": "string", "format": "date-time", "description": "When the contact was added to the campaign." }, "observed_at": { "type": "string", "format": "date-time", "description": "Time the server read the data." } }, "required": [ "object", "id", "workspace_id", "campaign_id", "username", "status", "external_id", "fields", "fields_truncated", "record_id_status", "first_contact_account", "first_message_sent_at", "first_reply_at", "delivery_state", "automation_state", "reason", "created_at", "observed_at" ], "additionalProperties": false, "description": "Lead: the participation of one contact in one campaign. The same person in two campaigns produces two different leads." }, "Fields": { "type": "object", "properties": { "record_id": { "anyOf": [ { "type": "string", "maxLength": 128 }, { "type": "null" } ], "description": "Record ID in an external CRM, passed when the contacts were uploaded. `null` if `record_id_status` is not `valid`." }, "first_name": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "First name." }, "last_name": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "Last name." }, "company": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "Company." }, "position": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "Job title." }, "website": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "Website." }, "source": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "Contact source." }, "utm_source": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "The `utm_source` tag." }, "utm_medium": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "The `utm_medium` tag." }, "utm_campaign": { "anyOf": [ { "type": "string", "maxLength": 1024 }, { "type": "null" } ], "description": "The `utm_campaign` tag." } }, "required": [], "additionalProperties": false, "description": "Contact record fields. Only the listed keys are returned; phone, email and internal variables are not returned. Values are up to 1024 characters, `record_id` up to 128, up to 8 KiB in total. A field missing from the contact record is absent from the object, except `record_id`: it is always present." }, "Account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Account ID." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account username without `@`. Can be `null`." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Account display name. Can be `null`." } }, "required": [ "id", "username", "name" ], "additionalProperties": false, "description": "Telegram account that sent the messages." }, "Message": { "type": "object", "properties": { "object": { "const": "message", "description": "Object type, always `message`." }, "id": { "type": "string", "minLength": 1, "description": "Opaque, stable message ID. Do not parse its format." }, "direction": { "type": "string", "enum": [ "outbound", "inbound" ], "description": "`outbound`: from the account to the lead; `inbound`: from the lead." }, "author": { "type": "string", "enum": [ "campaign", "manager", "lead", "unknown" ], "description": "`campaign`: a sequence step; `manager`: a manual message; `lead`: a lead reply; `unknown`: not determined." }, "sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the message was sent or received. `null` if unknown." }, "state": { "type": "string", "enum": [ "sent", "received", "unknown" ], "description": "`sent`: sending confirmed; `received`: incoming message saved; `unknown`: outcome not confirmed." }, "media_kind": { "type": "string", "enum": [ "none", "photo", "video", "voice", "audio", "document", "sticker", "animation", "video_note", "contact", "location", "poll", "other", "unknown" ], "description": "Attachment type. Files and links to them are not returned." }, "text": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "description": "Saved text, up to 4000 characters. `null` if the text is unavailable." }, "text_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`true`: the text is shortened; `false`: the text is complete; `null`: completeness is unknown." }, "text_unavailable": { "type": "boolean", "description": "`true` if the text is not returned. The reason is in `text_unavailable_reason`." }, "text_unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "not_saved", "ownership_unproven", "source_conflict", "purged" ] }, { "type": "null" } ], "description": "`not_saved`: the text was not saved; `ownership_unproven`: it is not proven that the message belongs to this conversation; `source_conflict`: sources disagree; `purged`: the text was deleted after the retention period." } }, "required": [ "object", "id", "direction", "author", "sent_at", "state", "media_kind", "text", "text_truncated", "text_unavailable", "text_unavailable_reason" ], "additionalProperties": false, "description": "A message from the saved conversation with a lead. The archive may be incomplete: see `meta.completeness`." }, "Text": { "type": "object", "properties": { "text": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "description": "Saved text, up to 4000 characters. `null` if the text is unavailable." }, "text_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "`true`: the text is shortened; `false`: the text is complete; `null`: completeness is unknown." }, "text_unavailable": { "type": "boolean", "description": "`true` if the text is not returned." }, "text_unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "not_saved", "ownership_unproven", "source_conflict", "purged" ] }, { "type": "null" } ], "description": "Reason the text is unavailable, or `null`." } }, "required": [ "text", "text_truncated", "text_unavailable", "text_unavailable_reason" ], "additionalProperties": false, "description": "Message text with completeness flags. Used in events with `include_text=true`." }, "Completeness": { "type": "object", "properties": { "overall": { "type": "string", "enum": [ "complete", "partial", "unknown" ], "description": "Overall completeness: `complete`, `partial` or `unknown`." }, "inbound": { "type": "string", "enum": [ "complete", "partial", "unknown" ], "description": "Completeness of inbound messages." }, "outbound": { "type": "string", "enum": [ "complete", "partial", "unknown" ], "description": "Completeness of outbound messages." }, "available_from": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Start of the period covered by the data. `null` if unknown." }, "available_to": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of the period covered by the data. `null` if unknown." }, "observed_at": { "type": "string", "format": "date-time", "description": "Time the server read the data." } }, "required": [ "overall", "inbound", "outbound", "available_from", "available_to", "observed_at" ], "additionalProperties": false, "description": "How complete the saved conversation archive with the lead is. Completeness is not calculated yet: `overall` and `inbound` are returned as `partial`, `outbound` as `unknown`." }, "EventLead": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Lead ID." }, "username": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Telegram username without `@`. Can be `null`." }, "status": { "type": "string", "enum": [ "new", "contacted", "completed", "replied", "blocked", "failed", "suspended", "deleted", "opted_out", "unknown" ], "description": "Lead status at the time of the event." }, "fields": { "$ref": "#/components/schemas/Fields", "description": "Contact record fields at the time of the event." }, "fields_truncated": { "type": "boolean", "description": "`true` if some values were shortened." }, "record_id_status": { "type": "string", "enum": [ "valid", "missing", "conflict", "unknown" ], "description": "Reliability of `fields.record_id`. In v1 events return `unknown`, and `fields.record_id` is `null`: get `record_id` from `GET /v1/leads/{id}` using `data.lead.id`." } }, "required": [ "id", "username", "status", "fields", "fields_truncated", "record_id_status" ], "additionalProperties": false, "description": "Snapshot of the lead at the time of the event." }, "Gap": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Interval ID." }, "from": { "type": "string", "format": "date-time", "description": "Start of the interval." }, "to": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "End of the interval. `null` if the interval is not closed yet." }, "state": { "type": "string", "enum": [ "open", "recovering", "recovered", "unrecoverable", "unknown" ], "description": "`open`, `recovering`, `recovered`, `unrecoverable` or `unknown`." } }, "required": [ "id", "from", "to", "state" ], "additionalProperties": false, "description": "Interval during which events may not have been fully collected." }, "Coverage": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "complete", "partial", "unknown" ], "description": "`complete`, `partial` or `unknown`." }, "gaps": { "type": "array", "items": { "$ref": "#/components/schemas/Gap" }, "maxItems": 50, "description": "Up to 50 intervals of possible incompleteness." }, "gaps_truncated": { "type": "boolean", "description": "`true` if there are more than 50 intervals." }, "incomplete_from": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest boundary of the hidden incomplete intervals. `null` if there are none." } }, "required": [ "status", "gaps", "gaps_truncated", "incomplete_from" ], "additionalProperties": false, "description": "Event feed completeness." }, "EventFirstMessageSent": { "type": "object", "properties": { "object": { "const": "event", "description": "Object type, always `event`." }, "id": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$", "description": "Event ID: `evt_` followed by 32 hexadecimal characters. The deduplication key." }, "api_version": { "const": "2026-10-18", "description": "Event format version." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the fact occurred." }, "test": { "const": false, "description": "Always `false`." }, "type": { "const": "lead.first_message_sent", "description": "Event type." }, "data": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization where the event occurred." }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name. Can be `null`." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Workspace at the time of the event." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name. Can be `null`." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Campaign at the time of the event. Can be `null`." }, "lead": { "$ref": "#/components/schemas/EventLead", "description": "Lead snapshot." }, "account": { "anyOf": [ { "$ref": "#/components/schemas/Account" }, { "type": "null" } ], "description": "Account that handled the conversation. `null` if unknown." }, "first_message_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the first message was sent. `null` if sending is not confirmed; this is common for reply events." }, "first_message": { "$ref": "#/components/schemas/Text", "description": "First message text. Only with `include_text=true`." } }, "required": [ "organization_id", "workspace", "campaign", "lead", "account", "first_message_sent_at" ], "additionalProperties": false, "description": "Event data." } }, "required": [ "object", "id", "api_version", "timestamp", "test", "type", "data" ], "additionalProperties": false, "description": "A first message was sent to the lead. `data.first_message` is present only with `include_text=true`." }, "EventLeadReplied": { "type": "object", "properties": { "object": { "const": "event", "description": "Object type, always `event`." }, "id": { "type": "string", "pattern": "^evt_[a-f0-9]{32}$", "description": "Event ID: `evt_` followed by 32 hexadecimal characters. The deduplication key." }, "api_version": { "const": "2026-10-18", "description": "Event format version." }, "timestamp": { "type": "string", "format": "date-time", "description": "When the fact occurred." }, "test": { "const": false, "description": "Always `false`." }, "type": { "const": "lead.replied", "description": "Event type." }, "data": { "type": "object", "properties": { "organization_id": { "type": "string", "format": "uuid", "description": "Organization where the event occurred." }, "workspace": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name. Can be `null`." } }, "required": [ "id", "name" ], "additionalProperties": false, "description": "Workspace at the time of the event." }, "campaign": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Name. Can be `null`." } }, "required": [ "id", "name" ], "additionalProperties": false }, { "type": "null" } ], "description": "Campaign at the time of the event. Can be `null`." }, "lead": { "$ref": "#/components/schemas/EventLead", "description": "Lead snapshot." }, "account": { "anyOf": [ { "$ref": "#/components/schemas/Account" }, { "type": "null" } ], "description": "Account that handled the conversation. `null` if unknown." }, "first_message_sent_at": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "When the first message was sent. `null` if sending is not confirmed; this is common for reply events." }, "reply": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Reply ID." }, "replied_at": { "type": "string", "format": "date-time", "description": "When the reply arrived." }, "automation_stopped": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the sequence stopped after the reply. `null` if the stop is not confirmed. Currently always `null`." }, "is_first_reply": { "type": "boolean", "description": "Whether this is the lead's first reply in the campaign. Not sent at the moment." }, "text": { "anyOf": [ { "type": "string", "maxLength": 4000 }, { "type": "null" } ], "description": "Reply text. Only with `include_text=true`." }, "text_truncated": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the text is shortened. Only with `include_text=true`." }, "text_unavailable": { "type": "boolean", "description": "Whether the text is unavailable. Only with `include_text=true`." }, "text_unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "not_saved", "ownership_unproven", "source_conflict", "purged" ] }, { "type": "null" } ], "description": "Reason the text is unavailable. Only with `include_text=true`." } }, "required": [ "id", "replied_at", "automation_stopped" ], "additionalProperties": false, "description": "Lead reply." } }, "required": [ "organization_id", "workspace", "campaign", "lead", "account", "first_message_sent_at", "reply" ], "additionalProperties": false, "description": "Event data." } }, "required": [ "object", "id", "api_version", "timestamp", "test", "type", "data" ], "additionalProperties": false, "description": "The lead replied. Sent for every counted reply, so one lead can have several. Text fields in `data.reply` are present only with `include_text=true`." }, "Problem": { "type": "object", "properties": { "type": { "type": "string", "description": "Error type URI: `urn:meliora:problem:`." }, "title": { "type": "string", "description": "Short error title in English." }, "status": { "type": "integer", "minimum": 400, "maximum": 599, "description": "HTTP status." }, "detail": { "type": "string", "description": "Explanation in Russian or English, based on the `Accept-Language` header. Do not parse this text in code." }, "instance": { "type": "string", "description": "Request URI: `urn:request:`." }, "code": { "type": "string", "description": "Machine-readable error code. Handle errors by `status` and `code`." }, "param": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Parameter the error refers to, or `null`." }, "request_id": { "type": "string", "format": "uuid", "description": "Request ID, the same as in the `Request-Id` header." } }, "required": [ "type", "title", "status", "detail", "instance", "code", "param", "request_id" ], "additionalProperties": false, "description": "An error in RFC 9457 format (`application/problem+json`)." }, "WorkspaceList": { "type": "object", "description": "Page of workspaces.", "properties": { "object": { "const": "list", "description": "Object type, always `list`." }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Workspace" }, "description": "Objects on the page." }, "has_more": { "type": "boolean", "description": "Whether there is more data after this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or `null` if there are no more pages." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "CampaignList": { "type": "object", "description": "Page of campaigns.", "properties": { "object": { "const": "list", "description": "Object type, always `list`." }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Campaign" }, "description": "Objects on the page." }, "has_more": { "type": "boolean", "description": "Whether there is more data after this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or `null` if there are no more pages." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "LeadList": { "type": "object", "description": "Page of leads.", "properties": { "object": { "const": "list", "description": "Object type, always `list`." }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Lead" }, "description": "Objects on the page." }, "has_more": { "type": "boolean", "description": "Whether there is more data after this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or `null` if there are no more pages." } }, "required": [ "object", "data", "has_more", "next_cursor" ], "additionalProperties": false }, "MessageList": { "type": "object", "description": "Page of messages.", "properties": { "object": { "const": "list", "description": "Object type, always `list`." }, "data": { "type": "array", "maxItems": 100, "items": { "$ref": "#/components/schemas/Message" }, "description": "Objects on the page." }, "has_more": { "type": "boolean", "description": "Whether there is more data after this page." }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page, or `null` if there are no more pages." }, "meta": { "type": "object", "description": "Archive completeness details.", "properties": { "completeness": { "$ref": "#/components/schemas/Completeness" } }, "required": [ "completeness" ], "additionalProperties": false } }, "required": [ "object", "data", "has_more", "next_cursor", "meta" ], "additionalProperties": false }, "EventsMeta": { "type": "object", "description": "Event feed details.", "additionalProperties": false, "required": [ "available_from", "retention_days", "collection", "coverage", "observed_at" ], "properties": { "available_from": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ], "description": "Earliest time for which the feed has events. `null` if unknown." }, "retention_days": { "const": 30, "description": "Number of days the feed retains events." }, "collection": { "$ref": "#/components/schemas/Collection" }, "coverage": { "$ref": "#/components/schemas/Coverage" }, "observed_at": { "type": "string", "format": "date-time", "description": "Time the server read the data." } } }, "EventList": { "type": "object", "description": "Page of the event feed.", "properties": { "object": { "const": "list", "description": "Object type, always `list`." }, "data": { "type": "array", "maxItems": 200, "items": { "oneOf": [ { "$ref": "#/components/schemas/EventFirstMessageSent" }, { "$ref": "#/components/schemas/EventLeadReplied" } ], "discriminator": { "propertyName": "type", "mapping": { "lead.first_message_sent": "#/components/schemas/EventFirstMessageSent", "lead.replied": "#/components/schemas/EventLeadReplied" } } }, "description": "Objects on the page." }, "has_more": { "type": "boolean", "description": "Whether there is more data after this page." }, "next_cursor": { "type": "string", "description": "Cursor for the next poll. Always present, even on an empty page." }, "meta": { "$ref": "#/components/schemas/EventsMeta" } }, "required": [ "object", "data", "has_more", "next_cursor", "meta" ], "additionalProperties": false } } }, "x-errors": { "invalid_parameter": { "status": 400, "title": "Invalid parameter", "detail_en": "Check the parameter value", "description": "The parameter value has an invalid format, is out of range or is used in an invalid combination. The parameter name is in `param`." }, "unknown_parameter": { "status": 400, "title": "Unknown parameter", "detail_en": "Unknown parameter", "description": "The route does not accept this parameter. An API key in the URL also causes this error." }, "cursor_mismatch": { "status": 400, "title": "Cursor mismatch", "detail_en": "The cursor does not match the request or access policy", "description": "The cursor is corrupted, was issued for a different route or filters, or the key's permissions and scope have changed." }, "invalid_api_key": { "status": 401, "title": "Invalid API key", "detail_en": "Provide a valid Bearer API key", "description": "The key is missing, invalid, revoked or expired." }, "scope_required": { "status": 403, "title": "Scope required", "detail_en": "The API key does not permit this read", "description": "The key does not have permission for this read. Texts also require \"Message text\" to be enabled." }, "api_disabled": { "status": 403, "title": "API disabled", "detail_en": "API access is disabled", "description": "API access is disabled in Meliora." }, "api_not_available": { "status": 403, "title": "API not available", "detail_en": "API read access requires Pro or higher", "description": "The organization's plan does not include the API. Read access requires Pro or higher." }, "subscription_inactive": { "status": 403, "title": "Subscription inactive", "detail_en": "An active subscription is required", "description": "The organization's subscription is not active." }, "module_not_available": { "status": 403, "title": "Module not available", "detail_en": "Sender is unavailable for this organization", "description": "The outreach module is unavailable for this organization." }, "organization_suspended": { "status": 403, "title": "Organization suspended", "detail_en": "Organization access is suspended", "description": "Organization access is suspended." }, "ip_not_allowed": { "status": 403, "title": "IP not allowed", "detail_en": "This IP address is not allowed by the key", "description": "The request came from an IP address that is not on the key's allow list." }, "not_found": { "status": 404, "title": "Not found", "detail_en": "Not found", "description": "The object was not found or is outside the key's scope. An unknown path also returns 404." }, "method_not_allowed": { "status": 405, "title": "Method not allowed", "detail_en": "Method not allowed", "description": "Only the GET method is allowed. The public endpoint answers other methods with a 404 without a body, so this code is not seen from outside." }, "cursor_expired": { "status": 410, "title": "Cursor expired", "detail_en": "The cursor expired. Restart a list without cursor. For the event feed, record the gap, request start=now, reconcile campaigns and leads, then resume the feed", "description": "The cursor expired: 15 minutes for lists, 30 days for the event feed." }, "rate_limit_exceeded": { "status": 429, "title": "Rate limit exceeded", "detail_en": "Request budget exceeded. Retry later", "description": "The request limit of the key, organization or IP address is exhausted. Retry after `Retry-After` seconds." }, "service_unavailable": { "status": 503, "title": "Service unavailable", "detail_en": "Data could not be read. Retry later", "description": "The data could not be read right now. Retry later." }, "server_busy": { "status": 503, "title": "Server busy", "detail_en": "The service is busy. Retry later", "description": "The service is overloaded. Retry after `Retry-After` seconds." }, "integration_initializing": { "status": 503, "title": "Integration initializing", "detail_en": "Access is still being prepared. Retry later", "description": "The new key is still being prepared. Retry later." } }, "x-limits": { "pro": { "key_second": 5, "key_minute": 300, "org_second": 10, "org_minute": 600, "key_concurrent": 5, "org_concurrent": 10, "max_response_bytes": 1048576, "mode": "normal" }, "premium": { "key_second": 10, "key_minute": 600, "org_second": 25, "org_minute": 1500, "key_concurrent": 5, "org_concurrent": 10, "max_response_bytes": 1048576, "mode": "normal" }, "enterprise": { "key_second": 10, "key_minute": 600, "org_second": 25, "org_minute": 1500, "key_concurrent": 5, "org_concurrent": 10, "max_response_bytes": 1048576, "mode": "normal" }, "emergency": { "key_second": 1, "key_minute": 60, "org_second": 2, "org_minute": 120, "key_concurrent": 1, "org_concurrent": 2, "max_response_bytes": 1048576, "mode": "emergency" } }, "x-key": { "pattern": "^mel_live_[A-Za-z0-9]{32}$", "max_active_keys": 10, "permissions": [ "campaigns:read", "leads:read", "messages:read", "events:read" ] } }