Conventions
Versions and changelog
How the API changes, what we promise not to break, and what changed when.
Two numbers
- The major version is in the path:
/api/v1. It changes only when something would break working code. - The API version is a number such as
1.0.0. Who am I returns it asapi_version, every event carries it in its body, and every webhook request has it in theMonotree-Api-Versionheader. It goes up when something is added: the last number for fixes and clarifications, the middle one for new endpoints, fields and event types.
You do not send a version. Every call to /api/v1 gets the newest 1.x.
The promise
Within v1 we only add:
- new endpoints;
- new optional fields and query parameters in requests;
- new fields in answers and in events;
- new event types (endpoints subscribed to
*get them); - new error types for new situations;
- new values in lists that are marked as open in the reference, such as
provisioning.stepand thechangeofsupport.thread.updated.
So write your code to ignore fields, event types and such values it does not know.
A change that would break working code (removing or renaming a field, changing a type, making an optional field required, changing what a call does) comes as /api/v2, announced at least six months ahead, with v1 kept running in that time.
Changelog
1.0.0 · 14 November 2026
The first public version. It contains:
Customers
- Create, read, change, submit, retry, suspend, resume and cancel customers, resend the admin invitation, and read a customer's timeline.
- Check a company ID and Find look-alike customers.
external_ref: your own reference, unique per mode, usable in place of the ID in every path (external_ref:<ref>).- List customers with the filters
status(several),updated_since,created_after,country,seller,external_ref,adoptionandq. - Logos as SVG or PNG; SVG logos are cleaned when stored.
Events and webhooks
- Signed webhook events with retries, a delivery log, redelivery, secret rotation with an overlap, and automatic pausing of an endpoint that only fails.
- List events: every event of the last 90 days, to catch up after downtime.
- Event types for customers, sellers, adoption alerts, the support desk and webhook endpoints: see Event types.
Sellers and security
- Sellers with roles, statuses and your own reference;
seller_refandseller_nameon a customer to credit it. Invite a seller and Reset two-factor sign-in. - List who can sign in and List the sign-in log.
Statistics, adoption and the statement
- Statistics per customer and for all customers, insights and headline numbers.
- Adoption alerts for customers that stall.
- The month as JSON or CSV, and the last 12 months.
The support desk
- Threads, messages, notes and attachments; the assistant's drafts and what it has been taught; escalations to Monotree; the desk's settings, presence and numbers. See The support desk.
Tokens and the sandbox
- Tokens with abilities and an optional expiry, created in the portal or over the API.
- A sandbox for every area, and Try it in the documentation.
Changes since the draft of 12 November 2026
A first draft of this API was documented on 12 November 2026, before any partner went live on it. If you read that draft or built against it, these things changed on the way to 1.0.0. They are listed once, here; from 1.0.0 on, a change of this kind only comes with /api/v2.
| Area | Before | Now |
|---|---|---|
| Customers | DELETE on a cancelled or deleted customer answered 409 |
Answers 200 with the customer |
| Customers | The company ID could change until the customer was live | It is fixed once the customer is submitted, except while its setup is failed |
| Customers | Two customers could share an external_ref |
An external_ref is unique per mode |
| Events | In customer.step, data.customer was one step behind details.step |
The customer is already on the next step |
| Webhooks | Any URL was accepted and a redirect was followed | The URL must lead to a public address, and a redirect counts as a failed delivery |
| Tokens | A token listed and revoked tokens of both modes, and could create a token with any ability | It lists and revokes tokens of its own mode only, and can give only abilities it has itself |
| Sellers | A seller had customers, counting every customer ever credited |
live_customers (live and suspended), with employees and signed_this_month |
| Sellers | Sellers were shared between live and sandbox | Sellers are kept apart per mode |
| Sellers | sellers:write could change anyone |
Changing, inviting or making an admin also needs admins:write; the last admin who can sign in cannot be disabled (409 last_admin) |
| Statement | seller in Get a month was a name, next to a seller_id |
seller is an object: id, name, external_ref |
| Statement | A month that is not a real month was accepted |
Answers 422 |
| Errors | A call a customer's state does not allow answered 409 invalid_status |
409 invalid_state, the same type the support desk answers |
| Customers | The field of an optional integration was accepted and stored for a partner that does not have that integration | Refused with 422 |
| Customers | seller on a customer had email |
seller is id, name, external_ref wherever a seller is named (customers, look-alikes, statement, statistics, sign-in log); the email is on Get a seller |
| Customers | delete_after of a deleted draft lay 30 days ahead |
null once a customer is deleted |
| Customers | List a customer's events answered a short form (summary, details) under the same evt_ ID |
The same event objects, filters and 90 days as List events |
| Customers | The list's seller took only sel_…, and seller_ref answered an empty list for an unknown seller |
seller takes sel_… or external_ref:<your reference>; an unknown seller answers 404. The seller_ref filter is gone |
| Events | An empty data.details was written [] |
Always an object: {} |
| Company IDs | A reserved ID got a suggestion such as admin2; a sandbox ID starting with taken got none |
No suggestion for a reserved ID; taken… gets one that adds a number |
| Sandbox | Retry a failed setup sent every customer.step again from the first step |
It goes on from the step that failed |
| Sellers | can_login stayed true for a disabled person |
false while they are disabled |
| Sellers | invite: true on Change a seller was ignored for someone with a password |
Answers 409 already_active, as Invite a seller |
| Sellers | updated_at moved on every sign-in |
Only when the person changes, so updated_since gives changes only |
| Sellers | No seller.updated when a person renamed themselves or a seller_name filled in a name |
seller.updated is sent |
| Security | List who can sign in had email and role inside seller |
seller is id, name, external_ref; email and role stand beside it |
| Security | The sign-in log took after (a time) and did not record a password changed on the account page |
The filter is created_after; the log has password.changed |
| Statistics | seller_ref on the statistics, the statement and the months |
seller takes sel_… or external_ref:<your reference> |
| Statistics | languages was [] when empty; adoption in customers_ranked had no flagged_at; a customer's rates could be decimals |
{}; one adoption shape everywhere; rates are whole numbers, computed the same way for one customer and for all |
| Adoption | List adoption alerts took state and had no seller filter |
status, and seller |
| Statement | Resuming a suspended customer changed the months it had been suspended in | A past month keeps counting it as suspended for the time it was |
| Statement | List the last 12 months always had twelve rows | Only months Get a month answers for |
| Webhooks | A token with webhooks:manage saw every endpoint, and its deliveries without their bodies |
It sees and touches only endpoints whose events it may all read; any other answers 404 |
| Support | A token could start a thread by mail to anyone at the mail domain of a customer's admin | Only to someone who has written before, or the admin Monotree invited, by the exact address |
| Support | Any file but a list of refused kinds went with an answer, a zip too |
A list of kinds that are taken; the content must be what the name says. Answers by chat, answers with files and the recipients of mails have limits |
| Support | q on List support threads searched every message |
It searches the subject, the summary, the latest words, who wrote and their company |
| Sellers | With sellers:write alone a token changed the email address of, and invited, any seller without a password |
Also needs admins:write for someone who is invited or has customers, and for a first invitation to a seller who has customers. An email change counts against the invitation limit |
| Customers | A seller_ref that is an email address added a seller with that address, or answered 422 when the address was in use |
It adds a seller whose external_ref is the address, needs sellers:write, and is limited to 60 an hour. The answer never depends on who else uses the address |
| Customers | No limit on drafts and sandbox customers | 200 drafts per mode and 500 sandbox customers that are not cancelled; more answers 409 limit_reached |
| IDs | An ID was also understood in capitals or without its prefix | Only exactly as it is given out; any other spelling answers 404 |
| Idempotency | Any token of the partner got the kept answer of a key; a call that never answered held its key for one minute | Only the token that sent the key gets the answer (409 idempotency_key_taken for another); five minutes |
| Support | A message's author was a name |
author is an object: type, name |
| Support | A thread's state: the field, the list filter and the PATCH field. The filter left snoozed threads out |
status in all three. The status filter is the thread's own status, snoozed or not; view is where the Support page shows it (view=open leaves snoozed threads out, view=snoozed has them) |
| Support | Change a support thread applied its fields one after another, and a refused field left the earlier ones changed | All or nothing: a refused call changes no field and sends no event |
| Support | Change the desk's settings needed hours with all seven days in every call |
Send only what changes; a day left out of hours keeps its hours |
| Support | idle_close_days was kept but closed nothing |
A thread that waits for the customer that long is closed by itself, once a day, with resolution no_response |
| Support | Follow up a released escalation did not check that the escalation was released | 409 invalid_state until it is; following up twice changes nothing |
| Support | An escalation's category was feature-request |
feature_request, as a thread's kind |
| Support | Monotree picking an escalation up (received) sent no event |
Every change of an escalation's status sends support.escalation.updated |
| Support | actor was always system on the support.message.* events and on what the assistant did |
Whoever did it: user, token or assistant on support.message.sent, customer on support.message.received, assistant on the auto_sent and human changes. Delivery reports stay system |
| Support | details of a thread's history and of support.thread.updated held an escalation as a number, and the assistant under another key |
escalation is its ID (esc_…); the key is assistant |
| Support | In Get support stats, the key of the customers, staff and waiting_ages rows was a name or the English label |
cus_…, sel_…, and a code from under_1h to over_3d; the name is in label |
| Support | Merging threads, sending a failed answer again, closing a thread on a draft, following up an escalation and setting the presence ignored Idempotency-Key |
They take it like every other POST |
| Support | A file of an answer was served with a cache lifetime of a day | Cache-Control: private, no-store |
| Support | A fault on our side inside a support call could answer 409 invalid_state with internal detail |
500 server_error; 409 invalid_state is only for what the desk refuses |
| Support | The tag for shift questions had a longer name | It is Shifts |
| Support | Get support stats had other field names | The names in the reference |
| Rate limits | 120 requests a minute per token | 120 a minute per partner and mode, 300 a minute per IP address before the token is checked, and lower limits for calls that send email, escalate, simulate, redeliver failed deliveries or rotate a secret |
| Support | A token could start an email thread to any address | email must be someone who has written before, a customer's admin, or at that admin's own mail domain (409 otherwise) |
| Support | Each file of an answer could be 25 MB | All the files of one answer are together at most 25 MB, and each is an object with only name and content |
| Support | – | A tag is a name of up to 60 characters or an integer id; q and a are at most 500 characters |
| Events | A token with customers:read read every event |
support.* events also need support:read and webhook_endpoint.* events webhooks:manage; other events are left out of the list and answer 404 |
| Events | data.seller was the whole seller |
It has no two_factor, passkeys or last_login_at |
| Sellers | two_factor, passkeys and last_login_at were always in a seller |
Only when the token has security:read |
| Tokens | A token that expires could create one that lasts longer, and revoking a token left the tokens it created | The new token needs an expires_at no later than its creator's (422), and revoking a token revokes every token it created, and those they created |
| Webhooks | – | response_body is the first 2,000 bytes of your server's answer, and deliveries are kept for 30 days |
| Idempotency | – | A key is kept per partner and mode: all your tokens of one mode share their keys |
| Branding | – | <style> elements in an SVG logo are removed: colour shapes with attributes |
| Security | – | A password has at least 10 characters, with letters and digits; the portal asks for the password again before sensitive steps, for 15 minutes at a time |
| Abilities | – | New: admins:write, security:read, support:configure |
| Webhooks | A token with webhooks:manage alone could subscribe an endpoint to any event and read every body back from the delivery log |
An endpoint is only subscribed to events the token may read (403 otherwise; * and no events need customers:read, support:read and webhooks:manage), also when its url or events change, and a delivery's payload and response_body are left out for event types the token may not read |
| Webhooks | A URL could be 500 characters; test events and redeliveries had the general limit only | At most 255 characters; 10 test events and redeliveries a minute to one endpoint |
| Sellers | sellers:write changed the email address and reset the two-factor sign-in of any seller |
For someone who has chosen a password both also need admins:write. A changed address emails the old one, signs the person out and voids their password-reset links |
| Sellers | Adding a seller with invite: false had the general limit only |
60 an hour per partner and mode |
| Support | A token could mail the admin (or the admin's domain) of any customer, a draft it had just made included | Only of a customer that is or has been live. More mail providers count as public, told by the registrable part of the domain (mail.yahoo.co.uk) |
| Support | Answers in a mail thread had the general limit only | 20 an hour to one thread and 200 an hour per partner and mode, sending a draft and sending a failed answer again included |
| Support | With auto: sends the assistant answered every turn it was sure of |
At most 3 answers by itself in one thread in 24 hours, and none to a sender who is not verified or not tied to a customer |
| Support | Any file could be sent with an answer | Programs, scripts and web pages are refused (422) |
| Customers | A deleted customer kept its admin's name and contact details, its support threads and the addresses in its events | They are removed; admin.name and admin.email can be null |
| Conventions | Dates in filters and bodies were any date PHP can read | Written the ISO way (2026-11-14 or 2026-11-14T09:00:00Z), between 1970 and 2100 in filters; expires_at and snoozed_until before 2038. A cursor with anything but our own values in it answers 400 invalid_cursor |
| Customers | A draft needed every field of a customer and terms_accepted |
A draft needs only company_name. Submit a draft checks the rest (422 with what is missing) and takes terms_accepted when the draft was made without it. On a draft company_id, url, country, employees, default_language, admin.name and admin.email can be null and languages empty |
| Support | Merging two threads that each had a draft of the assistant answered 500 |
The thread that stays keeps its draft; the drafts of the other come along as superseded |
| Conventions | A query parameter a call did not know was ignored, so a typo (?search=) or the old ?seller_ref= returned the whole list |
422 validation_error naming the parameter, on every GET. Unknown fields in a JSON body are still ignored |
| Customers | The field of an optional connection (the last section of Changing a customer) was in every customer, null for partners without it, and one partner's name was a reserved company ID |
The field is only in the answers and events of a partner that has the connection. Every partner's own name is a reserved company ID |
| Webhooks | A failed test event (ping) was tried again like a real event |
It is tried once, as documented: failed after one try |
| Webhooks | Sending a delivery again reset attempts and left no trace |
A delivery has redeliveries: how many times it was sent again |
| Statement | The CSV had no byte order mark, so Excel showed accented names wrong | It starts with a UTF-8 byte order mark and comes as text/csv; charset=utf-8 |
| Conventions | A body that was not valid JSON was read as an empty one (422, every field missing) |
400 invalid_json |
| Conventions | A message about one item of a list named its position ("The selected status.0 is invalid.") | It names the field ("The selected status is invalid."); the position is in the key of fields (status.0) |
| Lists | A cursor was a readable value that could be made by hand | It is signed and belongs to its list, partner and mode; anything else answers 400 invalid_cursor |
| Events | An unknown type filter answered an empty list |
422 |
| Support | status: closed on a dismissed thread answered 200 and changed nothing |
409 invalid_state; closing a closed thread still answers 200 |
| Support | An escalation showed in a thread's history as ticket |
escalation |
| Support | For a first message answered by itself (out of hours, or by the assistant) support.message.sent came before support.message.received |
support.message.received comes first |
| Statement | List the last 12 months answered without has_more and next_cursor |
The usual list shape, has_more always false |
| Sellers | sellers:write alone changed any seller's external_ref |
Changing or removing the reference of a seller who has customers, signs in or is invited also needs admins:write (403 otherwise) |
| Rate limits | A lower limit counted every call, also one refused with a 403, 404, 409 or 422, and showed its own numbers in the X-RateLimit-* headers; the portal counted apart |
It counts calls that did the thing, together with the portal's buttons; a refused call uses up no place, and X-RateLimit-* are always the general limit's. The rules |
| Rate limits | – | A token changes admin.email of a submitted customer at most 3 times a day (429) |
| Support | A token could go on answering in a mail thread with an address that was a customer's admin once | 409 invalid_state for an answer, a draft sent or an answer sent again when the address has never written in and is no longer the admin Monotree invited |
| Support | List people listed only people who had written by chat, also of cancelled customers | With customer, the invited admin comes first (admin: true, id null until there is a thread with them). People of customers that are cancelled, deleted or not live are left out. A person has admin |