Concepts

Requests and responses

Base URL, JSON, IDs, dates and time zones, money, null, and unknown fields.

Base URL and HTTPS#

Text

$QUILO_URL/api/v1

Always use HTTPS. Plain HTTP is not supported.

Methods#

Method	Use	Example
`GET`	Read a list or one record	`GET /api/v1/clients/{id}`
`POST`	Create	`POST /api/v1/tasks`
`PATCH`	Change some fields	`PATCH /api/v1/clients/{id}`
`DELETE`	Delete	`DELETE /api/v1/appointments/{id}`

PUT is not used: send only the fields you want to change with PATCH.

JSON bodies#

Send Content-Type: application/json and a JSON object of at most 64 KB. Every response is JSON in UTF-8.

Every record has an object field saying what it is (client, sale, custom_order, appointment, task, invoice, brand) and an id.

Unknown fields are refused#

If you send a field that does not exist (firstname instead of first_name), a read-only field (id, created_at), or a field you may not change (brand_id on PATCH), Quilo answers 422 validation_failed and lists each field. Nothing is saved. This way a typo never disappears silently.

IDs#

IDs are UUIDs such as 6f1c2a90-3b4d-4e5f-8a7b-9c0d1e2f3a4b. Keep Quilo's id in your system to update the same record later. To match records by your own number, store it in external_code (clients) or receipt_no (sales) and filter by it.

Dates and times#

Kind	Format	Example
Date	`YYYY-MM-DD`	`2026-10-17`
Date and time (sent)	ISO 8601 with time zone	`2026-10-20T14:00:00+02:00` or `2026-10-20T12:00:00Z`
Date and time (returned)	ISO 8601 in UTC	`2026-10-20T12:00:00+00:00`

Times without a time zone are refused, because "14:00" means different things in Zurich and Dubai.

Money#

Amounts are JSON numbers in the brand's currency (see currency on GET /brands), with at most two decimals: 2480, 2480.5, 2480.55. Do not send strings ("2'480.00").

Empty values#

Send null or an empty string to clear an optional field. Required fields cannot be cleared.

Text#

Text is trimmed. Each field has a maximum length (see the API reference). Quilo never interprets text as HTML; what you send is shown as plain text in the app.

Response headers#

Header	Meaning
`X-Request-Id`	Unique ID of this request. Send it to support when something goes wrong.
`X-RateLimit-Limit`	Requests allowed per minute for this key.
`X-RateLimit-Remaining`	Requests left in the current minute.
`Retry-After`	Only on `429`: seconds to wait.
`Idempotent-Replayed`	`true` when an earlier answer was replayed (see Idempotency).