هذه الصفحة غير متاحة بلغة العربية بعد، لذا تُعرض بالإنجليزية.
API conventions: money, lists, errors and limits
Minor-unit money, pagination and filters, the error shape, rate limits, Idempotency-Key and the headers on every answer.
- Base URL:
https://<workspace>.zmle.com/api/v1(or the workspace's own domain), orhttps://api.zmle.com/v1where the key selects the workspace. - JSON in and out (
content-type: application/json); dates are ISO 8601. - Money is an integer in minor units with an explicit
currency:105000withAEDmeans AED 1,050.00. X-Api-Version: 1andX-Request-Idon every answer — quote the request id to support.
Lists
Lists take ?page=1&per=25 (max 100), ?q= (search by name, number, e-mail …), ?status=SENT,PAID and ?since=<ISO> (rows changed since — use it to sync). They answer { data, page, per, total, pages } plus Link (first / prev / next / last) and X-Total-Count headers.
curl -s "$ZMLE_BASE/invoices?status=SENT,PAID&since=2026-10-01T00:00:00Z&per=50" \
-H "Authorization: Bearer $ZMLE_KEY"Errors
{
"error": {
"code": "validation_failed",
"message": "...",
"issues": [{ "path": "items.0.unitPrice", "message": "Expected integer" }]
}
}Single records come back as { data: {...} }; a create answers 201 { data }. Unknown routes answer 404, unsupported methods 405.
Rate limits
300 requests burst, then 5 requests per second, per key (or app sign-in) and per IP. Every answer carries X-RateLimit-Limit and X-RateLimit-Remaining; past the limit you get 429 with Retry-After. Repeated denials from one IP lead to a temporary ban, so back off instead of retrying in a loop.
Idempotency-Key
Send Idempotency-Key: <8–120 chars of A–Z a–z 0–9 _ . : -> on POST, PATCH and DELETE. The first answer is kept for 24 hours and replayed for a retry with the same body (header Idempotent-Replayed: true). The same key with another body answers 422 idempotency_key_reused; while the first call still runs you get 409. 5xx answers are not stored, so a retry runs again.
Written from: docs/API.md, src/lib/api-v1/pipeline.ts, src/lib/api-v1/docs.ts