Reading data

Read any system your customers connect through one consistent API. Every entity in the API Reference has two read endpoints, a list, GET /v4/<entity>, and a single record, GET /v4/<entity>/{id}, and both return the data Makini has synced from the system behind one connection.

Request

Response

Use a connection token

Reads need a connection-scoped access token with the connection:data:read scope. The token decides which connection you read from, so a request never names one. A plain client_credentials token has no connection, and every read with it answers 403. A connection that has been revoked, deactivated or deleted also answers 403. See the Access tokens guide.

Understand a record

Every record carries the same envelope fields, followed by the fields listed on its schema:

Field	Meaning
`id`	The Makini id: stable, never reused. Use it for `GET /v4/<entity>/{id}` and in filters.
`code`	The human-managed identifier (such as a work order number), or `null` where the system has none.
`_source`	The table or endpoint in the connected system the record came from.
`_idValue`	The connected system's own identifier for the record.
`_displayValue`	A short human-readable name. Never null.
`_createdAt`, `_updatedAt`	When the record was created and last changed (RFC 3339, UTC).
`_deletedAt`	When it was deleted in the connected system, or `null`.
`_implements`	The interfaces the record implements.
`customFields`	Your custom field mappings for this entity.
`_mappings`	Your own identifiers for this record, keyed by the mapping key you chose.

In customFields, every mapped key is present, and it is null where the record has no value.

Every declared field is always present

A field the connected system cannot supply is null, never missing. Timestamps are RFC 3339 in UTC.

Page through a list

Page with page (1-based, default 1) and per_page (1 to 100, default 25). A larger per_page is a 400, never silently clamped. The response is {data: [...], meta: {current_page, per_page}}, and meta carries no total count.

Soft-deleted records (with _deletedAt set) are excluded from lists.

Sort results

Use sort=<field> for ascending order and sort=-<field> for descending. The sortable fields are listed on each endpoint. The id is always the final tiebreaker, so paging is stable.

Sync incrementally

updatedSince returns only records whose _updatedAt is at or after that moment. _updatedAt is the observed change time, so this is the cursor for incremental sync.

It takes a date (2026-09-01, meaning midnight UTC) or an RFC 3339 date-time with an offset (2026-09-01T08:00:00Z or 2026-09-01T10:00:00+02:00). A date-time without an offset is a 400.

To narrow a list further, see the Filtering guide. To pull related records into the same response, see Relations and expand.

Fetch a single record

GET /v4/<entity>/{id} takes the Makini id (the id field), not the connected system's identifier (_idValue). The body is {data}: the same record shape the list returns, with no meta. expand works exactly as on the list.

Reference

Not found

Temporarily unavailable

Next steps

Filtering

Narrow any list to the records you need.

Relations and expand

Follow links between records, or pull them inline.

Access tokens

Get the connection-scoped token every read needs.

Errors

Read the error body and handle each status.

Use a connection token#

Understand a record#

Page through a list#

Sort results#

Sync incrementally#

Fetch a single record#

Reference#

Next steps#

Use a connection token

Understand a record

Page through a list

Sort results

Sync incrementally

Fetch a single record

Reference

Next steps