Response format

The JSON envelope depends on the operation type. Three shapes are used.

Fetching a single resource

GET /v1/{resource}/{id}:

{
  "statusCode": 200,
  "data": { /* the requested object */ }
}

Fetching a list

GET /v1/{resource}:

{
  "statusCode": 200,
  "data": [ /* array of objects */ ],
  "meta": {
    "pagination": {
      "total_items": 100,
      "items_per_page": 10,
      "total_pages": 10,
      "current_page": 1,
      "offset": 0,
      "has_previous_page": false,
      "has_next_page": true,
      "next_page": 2,
      "previous_page": null
    },
    "generated_at": "2026-05-07T14:32:11.000Z"
  }
}

Bulk writes

POST / PUT / bulk-delete:

{
  "statusCode": 200,
  "sent_count": 18,
  "rejected_count": 2,
  "rejected_items": [ /* index, original payload, validation errors */ ]
}

Processing is asynchronous: a 200 confirms acceptance, not immediate visibility on subsequent reads. See also Error codes.

Pagination, filtering, sorting, projection

Listing endpoints accept the standard parameters:

Parameter	Role
limit	Number of items per page
offset	Starting offset
filters	Filtering criteria
order	Sorting
fields	Projection: return only certain fields

Mapping with the JavaScript SDK

The SDK wraps every response in { ok, statusCode, data, error }. The API body lives in res.data:

// List
const page = await SpmCustomers.list(client, { limit: 50, offset: 0 });
if (page.ok) {
  console.log(page.data);                  // array of objects (API data)
  // the API pagination is exposed as-is in the response
}

// Single item
const one = await SpmCustomers.get(client, 'cust_1');
console.log(one.data);                      // the object (API-side data.data depending on the endpoint)

// Bulk write
const res = await SpmCustomers.bulkSave(client, items, { chunk: true });
if (res.ok) {
  console.log(res.data.sent_count, res.data.rejected_count);
  console.log(res.data.chunks);             // per-chunk detail when chunking is enabled
}

With chunking enabled, the SDK aggregates the counters from all chunks into a single envelope — see Resilience.