---
title: Your first request
description: "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](/guides/start/connect-a-client), and every path below is relative to `/api/v1`.

## 1. Read your capabilities

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

```json
{
  "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

```http
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`](/reference/crm/post-api-v1-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

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

```json
{
  "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](/guides/concepts/views-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](/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](/guides/errors) covers the refusal shape and which refusals are worth retrying.