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 as api_version, every event carries it in its body, and every webhook request has it in the Monotree-Api-Version header. 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.step and the change of support.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, adoption and q.
  • 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

Statistics, adoption and the statement

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