Conventions

Response envelope, error format, and cursor pagination.

Every /v1 response follows the same shape, regardless of resource. Once you've integrated one endpoint, you've integrated all of them.

Successful responses wrap the payload in data and carry pagination hints in meta:

{
  "data": { "status": "ok" },
  "meta": {
    "cursor": null,
    "hasMore": false
  }
}

• data — the resource or list of resources. Never null on success.
• meta.cursor — opaque string; pass it to the next request to continue paginating. null when there's no next page.
• meta.hasMore — true if more pages exist.

Errors return a structured body regardless of HTTP status:

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid Bearer token.",
    "details": {}
  }
}

• code — stable machine-readable identifier ("unauthorized", "not_found", "rate_limited", "invalid_argument", etc.). Safe to switch on.
• message — human-readable string. Good for logs; not safe to show verbatim in end-user UIs without translation.
• details — optional, per-code. For validation errors, contains a field-keyed map of specifics.

Common HTTP statuses:

List endpoints accept two query parameters:

• limit — integer, default 20, max 100. Values above 100 are clamped silently.
• cursor — opaque string from a previous response's meta.cursor. Omit on the first request.

Pagination is forward-only and cursor-based — there are no page numbers. The cursor encodes sort position; it is stable across new records being added.

GET /v1/clients?limit=50
GET /v1/clients?limit=50&cursor=eyJpZCI6MTIzfQ

When meta.hasMore is false, stop paginating.

Text fields are length-bounded server-side. Oversized input is rejected with 400 invalid_argument (never a 5xx); the error message names the field that was too long, so you can shorten it and retry. Current caps:

Lengths are counted in Unicode characters (code points), not bytes.

Every request is scoped to the organization that owns the Bearer key. Objects that belong to a different organization return 404 (not 403) — Salfio does not leak the existence of other orgs' data.