Quick start
You need a MARREK account on a plan that includes the API (currently Business and Pro). Only the account owner can create keys and webhooks.
- In the dashboard open Developers → API keys and press “Create key”. Choose what the key may do and, optionally, which projects it may reach. Copy the key (it starts with mk_live_) — it is shown once.
- Call the API from your server with the key as a bearer token. First, list your projects:
curl https://marrek.app/api/public/v1/projects \
-H "Authorization: Bearer mk_live_YOUR_KEY"Response
{
"data": [
{ "id": 42, "name": "Shoe Store", "slug": "shoe-store-x1y2z3", "ai_enabled": true }
]
}Then read dialogs of a project (pass its id in X-Project-Id) and send a reply:
curl "https://marrek.app/api/public/v1/threads?per_page=20&channel=telegram" \
-H "Authorization: Bearer mk_live_YOUR_KEY" \
-H "X-Project-Id: 42"curl -X POST https://marrek.app/api/public/v1/threads/1001/messages \
-H "Authorization: Bearer mk_live_YOUR_KEY" \
-H "X-Project-Id: 42" \
-H "Content-Type: application/json" \
-d '{"content": "Hello! Your order has shipped."}'Response
{
"data": {
"id": 5120,
"thread_id": 1001,
"direction": "outbound",
"sender_type": "manager",
"content": "Hello! Your order has shipped.",
"delivery_status": "pending",
"metadata": { "source": "api", "api_key_id": 7 },
"attachments": [],
"created_at": "2026-09-29T12:00:00.000000Z"
}
}Authentication
Send the key in the Authorization header: Authorization: Bearer mk_live_… . The base URL is https://marrek.app/api/public/v1. All requests and responses are JSON over HTTPS.
A key acts as the account owner who created it. It works while that person is active and still owns the account; if either stops being true, the key stops working.
| Status | error.code | Meaning |
|---|---|---|
| 401 | invalid_api_key | Missing, malformed or unknown key |
| 401 | api_key_revoked | The key was revoked in the dashboard |
| 401 | api_key_expired | The key passed its expiry date |
| 401 | api_key_disabled | The owner who created the key no longer has access |
| 402 | plan_limit_exceeded (error.limit = api_access) | The account’s plan does not include the API — checked on every request |
| 429 | too_many_auth_failures | Too many wrong keys from your IP — wait and retry |
Projects
An account can have several projects (workspaces): each has its own dialogs, leads, products, knowledge base and AI settings. Every request works inside exactly one project.
- Send the project id in the X-Project-Id header. GET /projects lists the ids your key can use.
- If the key can reach only one project, you may omit the header — it is chosen automatically.
- If it can reach several and you send none, the answer is 409 with error.code = project_required.
- A project outside the key’s allowed list answers 403 project_forbidden.
Error shape
{
"message": "Select a project with the X-Project-Id header.",
"error": { "code": "project_required" }
}Access scopes
When you create a key you choose, for each area, no access, read, or read and write. “Write” always includes “read”. A request outside the key’s scopes answers 403 insufficient_scope, and the response lists what was required.
| Scope | Allows |
|---|---|
| dialogs:read | List and open dialogs, read messages |
| dialogs:write | Send messages, mark as read, change a dialog’s AI switch and lead status, upload attachments |
| leads:read / leads:write | Read and export leads / edit and delete them |
| catalog:read / catalog:write | Read products and categories / create, edit, delete them |
| knowledge:read / knowledge:write | Read / manage knowledge base documents |
| ai_settings:read / ai_settings:write | Read / change the AI prompt and behaviour |
| analytics:read | Read statistics |
Give each integration the least it needs. A key that only feeds your BI tool needs analytics:read and nothing else.
Requests, errors and limits
- Pagination — list endpoints take page and per_page (1–100) and answer { data, links, meta }. Message history is paged backwards with before_id and limit.
- Filtering — dialogs and leads accept the same filters as the dashboard (channel, status, q, date_from, date_to …); see the reference.
- Products — category_id returns products of that category and of all its subcategories; q and is_active narrow the list further.
- Rate limit — 120 requests per minute per key. Every response carries X-RateLimit-Limit and X-RateLimit-Remaining; when exceeded you get 429 with Retry-After.
- Timestamps are ISO 8601 in UTC. Send X-Timezone (for example Europe/Kyiv) to have day filters and analytics use your calendar day; a time zone pinned in the key owner’s dashboard settings takes precedence.
| Status | When |
|---|---|
| 400 | X-Project-Id is not a number (invalid_project_id) |
| 401 / 403 | See Authentication and Access scopes |
| 404 | The resource does not exist in this project (or belongs to another) |
| 409 | project_required, or a state conflict such as ai_enable_conflict |
| 422 | Validation failed — errors lists each field |
| 429 | Rate limited |
Validation errors
{
"message": "The name field is required.",
"errors": { "name": ["The name field is required."] }
}Sending a message answers 201 with delivery_status: pending — the message is queued for the customer’s channel. The final status (delivered or failed) arrives as a message.updated webhook, or read it again from the dialog.
Sending an attachment
# 1. Ask for an upload URL
curl -X POST https://marrek.app/api/public/v1/media/upload-url \
-H "Authorization: Bearer mk_live_YOUR_KEY" -H "X-Project-Id: 42" \
-H "Content-Type: application/json" \
-d '{"filename": "photo.jpg", "content_type": "image/jpeg", "size_bytes": 204800}'
# → { "url": "https://…", "headers": { "Content-Type": "image/jpeg" }, "key": "tenants/42/outgoing/….jpg", "kind": "image" }
# 2. PUT the file to that url, sending exactly the returned headers
curl -X PUT "<url>" -H "Content-Type: image/jpeg" --data-binary @photo.jpg
# 3. Send the message, referencing the key
curl -X POST https://marrek.app/api/public/v1/threads/1001/messages \
-H "Authorization: Bearer mk_live_YOUR_KEY" -H "X-Project-Id: 42" \
-H "Content-Type: application/json" \
-d '{"content": "Here is the photo", "attachment_key": "tenants/42/outgoing/….jpg",
"attachment_kind": "image", "attachment_mime_type": "image/jpeg", "attachment_size_bytes": 204800}'Webhooks
Instead of polling, let MARREK call you. In Developers → Webhooks add the URL of an endpoint on your server, choose which events and projects you want, and copy the signing secret (shown once). MARREK then sends an HTTPS POST for every matching event.
Every request looks like this:
POST /marrek/webhook HTTP/1.1
Content-Type: application/json
User-Agent: Marrek-Webhooks/1
X-Marrek-Event-Id: 0198c7a1-5b3e-7c11-9f0a-2d6e4b8a1c33
X-Marrek-Event-Type: message.received
X-Marrek-Timestamp: 1790683200
X-Marrek-Delivery-Attempt: 1
X-Marrek-Signature: t=1790683200,v1=5f2b6c…e91aBody of message.received (abbreviated)
{
"id": "0198c7a1-5b3e-7c11-9f0a-2d6e4b8a1c33",
"type": "message.received",
"api_version": "v1",
"created_at": "2026-09-29T12:00:00Z",
"account_id": 7,
"project_id": 42,
"data": {
"object_type": "message",
"object": {
"id": 5119,
"thread_id": 1001,
"direction": "inbound",
"sender_type": "customer",
"content": "Do you have size 42?",
"has_attachments": false,
"attachments": [],
"delivery_status": "received",
"created_at": "2026-09-29T12:00:00.000000Z"
},
"thread": {
"id": 1001,
"channel": "telegram",
"customer_name": "Olena",
"customer_username": "olena_k",
"status": "unread",
"ai_enabled": true,
"lead_status": null
}
}
}The object inside data is exactly what the corresponding REST endpoint returns, so you learn one shape. Message events also carry the dialog in data.thread so you know who wrote without a second call. “Updated” events add data.changes with the previous and new value of each field that changed:
thread.updated
{
"type": "thread.updated",
"data": {
"object_type": "thread",
"object": { "id": 1001, "lead_status": "ready_to_close", "ai_enabled": false },
"changes": {
"lead_status": { "from": "interested", "to": "ready_to_close" },
"ai_enabled": { "from": true, "to": false }
}
}
}| Event | When |
|---|---|
| message.received | A customer wrote a message (Telegram, Instagram, web widget) |
| message.sent | A reply was created — by the AI, a manager or the API |
| message.updated | A message changed: its delivery status, or an attachment finished downloading (now has a url) |
| thread.created | A new dialog started |
| thread.updated | A dialog’s status, AI switch, assignee, lead status or closure changed |
| lead.created | The first contact details of a customer were captured |
| lead.updated | A lead was updated by the AI or edited by a person |
| lead.deleted | A lead was deleted (the payload holds its last state) |
Verifying signatures
Anyone can POST to your URL, so verify that a request really comes from MARREK before trusting it. Each request carries X-Marrek-Signature: t=<unix time>,v1=<hex>. The signature is HMAC-SHA256, keyed with your endpoint’s secret, over the string "<t>.<raw request body>".
- Use the raw body exactly as received — parsing and re-serialising the JSON changes the bytes.
- Reject requests whose timestamp is more than 5 minutes off your clock (replay protection).
- Compare with a constant-time function.
- While you rotate a secret the header carries a v1= value for the old and the new secret; accept the request if any of them matches.
<?php
// $secret is the whsec_… value shown when you created the endpoint.
$payload = file_get_contents('php://input'); // the RAW body — do not decode it first
$header = $_SERVER['HTTP_X_MARREK_SIGNATURE'] ?? '';
$timestamp = null;
$signatures = [];
foreach (explode(',', $header) as $piece) {
[$key, $value] = array_pad(explode('=', trim($piece), 2), 2, '');
if ($key === 't') { $timestamp = (int) $value; }
if ($key === 'v1') { $signatures[] = $value; } // several while a secret is being rotated
}
if ($timestamp === null || abs(time() - $timestamp) > 300) {
http_response_code(400); exit('stale or malformed timestamp');
}
$expected = hash_hmac('sha256', $timestamp . '.' . $payload, $secret);
$valid = false;
foreach ($signatures as $signature) {
$valid = $valid || hash_equals($expected, $signature); // constant-time compare
}
if (! $valid) { http_response_code(401); exit('bad signature'); }
$event = json_decode($payload, true);
// De-duplicate on $event['id'], enqueue the work, and answer quickly:
http_response_code(200);Delivery, retries and reliability
Answer with any 2xx status within 10 seconds — do the real work in a queue. Delivery is at-least-once: the same event can arrive more than once, so de-duplicate on the event id (also sent as X-Marrek-Event-Id); it stays the same on every retry. Events are not guaranteed to arrive in order — use created_at and the object’s own timestamps.
| Your answer | What MARREK does |
|---|---|
| 2xx | Delivered — done |
| 408, 429, 5xx, timeout, network or TLS error | Retries with growing delays (about 30 s, 1 min, 2 min … up to 1 h), up to 10 attempts in 24 hours; honours Retry-After |
| Other 4xx (400, 401, 403, 404, 410, 422 …) | Not retried — treated as a configuration problem. Fix it and replay from the delivery log |
| 3xx | Redirects are not followed — use the final URL |
- If your endpoint keeps failing it is paused for a few minutes so we do not hammer it, and switched off after 72 hours of failures. Events are kept and can be replayed after you enable it again.
- The Delivery log in the dashboard shows every attempt with your server’s answer and the exact payload, and can replay one delivery or everything that was missed.
- Replies you send through the API arrive back as message.sent events with metadata.source = "api" — ignore those if you only want to react to other people’s messages.
- Attachment url values are signed and expire after 6 hours; fetch the message again for a fresh link.
- You can change the signing secret at any time. For 24 hours requests are signed with both, so you can switch without downtime.
Questions
- Does sending a message through the API use my AI message allowance? No — it is a manager-style message. AI replies to customers count as usual.
- Which plans include the API? Business and Pro at the moment; the plan list in your dashboard always shows the current answer. If you downgrade, your keys and endpoints are kept but requests answer 402 and no webhooks are sent — upgrade to bring them back, and replay whatever was skipped from the delivery log.
- Can several people create keys? Keys and webhooks are managed by the account owner only.
- Can I limit a key to one shop? Yes — choose the projects when creating the key.
- Is there an SDK? Not yet. The OpenAPI document works with generators such as openapi-generator.
- Something is unclear or missing? Write to [email protected].
All requests go to https://marrek.app/api/public/v1
