Your first request

From a fresh access token to a page of records: read your capabilities, find the object, then list it — and recognise the four refusals that come first.

Three requests. You need an access token from connecting a client, and every path below is relative to /api/v1.

1. Read your capabilities

GET /api/v1/capabilities
Authorization: Bearer <token>

{
  "actions": ["objects.read", "records.read", "records.write"],
  "features": { "api": true, "cpq": true, "approvals": false },
  "revision": 7
}

Start here rather than probing. actions is what this token and this member are actually allowed to do, drawn from the twenty-one that exist. features is the on/off state of the eight modules. revision is the module policy’s revision, so you can tell a changed configuration from a changed record.

The endpoint’s own description puts it plainly: poll this rather than inferring entitlements from a refusal. A 403 tells you something is wrong; capabilities tells you what you have.

2. Find the object

GET /api/v1/objects

Each entry carries a key, a label, a kind, the moduleKey that owns it, and a revision.

Two things to expect. The list is filtered by your access — a member who cannot read an object does not see it, so this is not the workspace’s full schema. And the standard objects have to be installed before they exist: POST /bootstrap creates the ones the enabled modules own. On a workspace nobody has set up, this list is empty rather than wrong.

Match on key — account, lead, opportunity. The labels are Japanese, because they are display copy.

3. List its records

GET /api/v1/objects/{objectId}/records?limit=10

{
  "items": [{ "id": "…", "name": "…", "revision": 3, "values": {} }],
  "nextCursor": "…",
  "total": 42
}

limit runs from 1 to 100 and defaults to 50. Pass nextCursor back as after for the next page and stop when it is null.

total is counted on the first page only; every later page answers total: null. Hold the first page’s figure if you want to show one.

That is the whole minimum. Ordering, views, filters and related records are all optional, and views, ordering and pagination covers them — including the four parameter combinations that are refused.

The four refusals that come first

Refusal	What it means	What to do
`workspace_session_required`	You called `/api/v1/workspace/…`, the web application’s transport. It refuses bearer tokens by design	Use the paths in the reference
`permission_required`	The token’s scope or the member’s role does not allow the action	Read `capabilities`; the action you want is not in `actions`
`feature_disabled`	The endpoint’s module is off for this workspace	Read `capabilities`; the module is `false` in `features`
An empty object list	Nobody has run `POST /bootstrap`	Install the standard objects, or ask an administrator to

The first three are the same mistake in three forms: asking the API what you may do instead of reading capabilities first.

A 401 is different in kind — the token is missing, malformed or revoked, and the answer is to get a new one rather than to change the request. Errors covers the refusal shape and which refusals are worth retrying.