Fundamentals

Requests and responses

Envelope, error shape, trace_id, and the two response contracts — which endpoint uses which.

Two contracts, two contexts

Blesyum has two response shapes, and confusing them is the most common mistake.

Core and module panel endpoints

Envelope: {data, trace_id}

json
{ "data": { "id": "0193…", "name": "Acme Ltd." }, "trace_id": "01JC7…" }

Error:

json
{ "error": {
    "code": "CORE-REQ-0002",
    "message": "Validation failed.",
    "hint": "validation",
    "trace_id": "01JC7…",
    "details": [{ "field": "email", "message": "Not a valid email address." }]
} }

Public API endpoints (/public/v1/...)

These use an Intercom-compatible shape so existing client libraries work:

json
{ "type": "list",
  "data": [ { "type": "contact", "id": "0193…" } ],
  "pages": { "type": "pages", "per_page": 50, "next": { "starting_after": "eyJ…" } } }

Error:

json
{ "type": "error.list",
  "errors": [{ "code": "parameter_invalid", "message": "per_page can be at most 150." }] }

A module has both panel endpoints and public API endpoints, and their shapes differ. If public appears in the path, expect the second shape.

trace_id — send this when you ask for support

Every response carries a trace_id. If you include it when reporting a problem, we can find the exact request in our logs. Store it on your side too: the difference between "sometimes I get a 500" and "I got a 500 on this trace_id" is the difference between hours of investigation and a five-second lookup.

The error code is a CONTRACT

code is stable and shaped DOMAIN-AREA-NNNN:

text
CORE-AUTH-0001    core · auth · 401
CORE-REQ-0002     core · request · 422 (validation)
CRM-LIC-0001      CRM · licence · 403
ERP-FATURA-0007   ERP · invoicing · module-specific

Branch on code, not on message. message is translated to the reader's language and improves over time; code does not change.

Full list: Error codes.

Content type and encoding

  • Request body: application/json, UTF-8
  • Response: application/json; charset=utf-8
  • Dates: RFC 3339, UTC (2026-08-21T09:14:00Z)
  • Money: integer minor units plus a separate currency field — we do not use floating point (to avoid the 0.1 + 0.2 problem)

Body size

The default ceiling for JSON endpoints is 1 MiB. Upload endpoints have their own, wider ceilings; exceeding it gives 413 and CORE-REQ-0006.

Time

Server time is canonical. No endpoint makes a duration or access decision based on a date sent by the client; trial, licence and session decisions are all made server-side. If your own UI shows "days remaining", take the reference from GET /api/v1/time — a device clock is an opinion, not evidence.

Bu sayfa işine yaradı mı?