API conventions

Requests and responses

• JSON in and out, content-type: application/json. Request bodies have a size cap; documents travel base64-encoded in JSON.
• GET reads, POST changes. Deletes are POST .../delete, and most changes are named actions such as POST /api/invoices/:id/hold.
• Responses carry Cache-Control: no-store and security headers (CSP, X-Frame-Options: DENY, Referrer-Policy: no-referrer).

Errors

Every error has the same shape:

{ "error": { "code": "invalid_request", "message": "Request did not validate", "details": [{ "path": "lines.0.quantity", "message": "Number must be greater than 0" }] } }

Status	Codes	Meaning
400	invalid_request	The body or query did not validate; details lists each problem
401	unauthenticated	No valid token
403	permission_denied, sod_violation, staff_only	The person lacks the duty, or doing it would break segregation of duties
404	not_found	No such record in this tenant
409	invalid_state	The record is not in a state that allows the action
422	policy_violation and other domain codes	The policy pack does not allow it, such as a late bid
500	internal	Logged on the server

Lists

Every list endpoint takes the same query parameters:

Parameter	Meaning
q	Free text, matched case-insensitively against the row’s search text
sort, dir	A sortable column and asc or desc
page	1-based
pageSize	Default 25, at most 5000 so an export can take everything
any declared filter	Such as status=exception,on_hold; comma-separated values mean “any of”

The response holds the rows under a named key (invoices, requisitions…), plus page (page, pageSize, total, pages, sort, dir, q) and facets: counts for each filter’s values, computed before that filter applies.

Amounts and dates

• Amounts in records are integers in minor units (cents), in fields ending Minor, such as totalMinor. Some request bodies, such as a manually entered invoice, take dollars as numbers; the reference says which.
• Dates are YYYY-MM-DD; times are ISO 8601 in UTC.
• Ids are opaque strings with a type prefix, such as inv_... or sup_....