# Directory endpoints

> Members and groups — ids, names, roles; never email addresses. Every operation with parameters, body, responses, errors and examples.

Source: https://developers.processcart.com/reference/directory

Members and groups — ids, names, roles; never email addresses.

Base URL `https://app.processcart.com/api/v1`. Every operation below is also in the [OpenAPI document](https://developers.processcart.com/openapi.json) and the [interactive reference](https://developers.processcart.com/reference).

| Operation | Method and path | Scope |
| --- | --- | --- |
| [List members](#listUsers) | <code class="pc-docs-wrap">GET /v1<wbr>/users</code> | Scope `users:read` |
| [List groups](#listGroups) | <code class="pc-docs-wrap">GET /v1<wbr>/groups</code> | Scope `users:read` |

## GET /v1/users
**List members.** Scope `users:read` · paginated (`{ data, nextCursor, hasMore }`). Operation id `listUsers` · [open in the API reference](https://developers.processcart.com/reference#tag/directory/GET/v1/users).

The workspace's members in the order they joined: user id, display name, role (`member`, `builder`, `admin`) and avatar. Email addresses are not exposed. Use the ids to read assignees and to filter runs with `assignee=u:<id>`.

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [ListUsersResponse](https://developers.processcart.com/reference/schemas#listusersresponse) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "a5340bfc-1ba6-429e-97b3-ac741f62ffdf",
      "name": "Fixture Admin",
      "role": "admin",
      "avatarUrl": null,
      "joinedAt": "2026-10-10T17:44:11.041Z"
    },
    {
      "id": "7a632343-8bfa-4b60-849a-aaad7fcd7b4c",
      "name": "Fixture Member",
      "role": "member",
      "avatarUrl": null,
      "joinedAt": "2026-10-10T17:44:11.272Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```


## GET /v1/groups
**List groups.** Scope `users:read` · paginated (`{ data, nextCursor, hasMore }`). Operation id `listGroups` · [open in the API reference](https://developers.processcart.com/reference#tag/directory/GET/v1/groups).

The workspace's groups by name, each with the ids of its current members. Groups appear as `{ kind: "group" }` assignees and in `assignee=g:<id>` filters.

**Query parameters** (an unknown parameter is a 422 `validation_failed` with `errors[].code = "unknown_parameter"`)

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `limit` | integer | no |  |
| `cursor` | string | no | The `nextCursor` of the previous page. Opaque, and bound to the query that produced it — a cursor from a different filter or sort is a 422. |

**Responses**

| Status | Meaning | Body |
| --- | --- | --- |
| 200 | OK. | [ListGroupsResponse](https://developers.processcart.com/reference/schemas#listgroupsresponse) |
| 401 | No usable credential. `unauthorized` — Authentication required; `invalid_api_key` — Invalid API key; `key_revoked` — API key revoked. | [Problem](https://developers.processcart.com/errors) |
| 403 | `insufficient_scope` — Insufficient scope. | [Problem](https://developers.processcart.com/errors) |
| 405 | The verb is not supported on this path. `method_not_allowed` — Method not allowed. | [Problem](https://developers.processcart.com/errors) |
| 422 | `validation_failed` — Validation failed. | [Problem](https://developers.processcart.com/errors) |
| 429 | `rate_limited` — Too many requests. | [Problem](https://developers.processcart.com/errors) |
| 500 | `internal_error` — Internal error. | [Problem](https://developers.processcart.com/errors) |
| 503 | `unavailable` — Service unavailable. | [Problem](https://developers.processcart.com/errors) |

**Errors** (every code this operation can answer; see [Errors](https://developers.processcart.com/errors))

- 401 [`invalid_api_key`](https://developers.processcart.com/errors#invalid_api_key) — Invalid API key
- 401 [`key_revoked`](https://developers.processcart.com/errors#key_revoked) — API key revoked
- 401 [`unauthorized`](https://developers.processcart.com/errors#unauthorized) — Authentication required
- 403 [`insufficient_scope`](https://developers.processcart.com/errors#insufficient_scope) — Insufficient scope
- 405 [`method_not_allowed`](https://developers.processcart.com/errors#method_not_allowed) — Method not allowed
- 422 [`validation_failed`](https://developers.processcart.com/errors#validation_failed) — Validation failed
- 429 [`rate_limited`](https://developers.processcart.com/errors#rate_limited) — Too many requests
- 500 [`internal_error`](https://developers.processcart.com/errors#internal_error) — Internal error
- 503 [`unavailable`](https://developers.processcart.com/errors#unavailable) — Service unavailable

**Example response** (200)

```json
{
  "data": [
    {
      "id": "bca06b45-d08f-4b9a-a769-1ad979a0dfd6",
      "name": "Reviewers",
      "memberIds": [
        "7a632343-8bfa-4b60-849a-aaad7fcd7b4c"
      ],
      "createdAt": "2026-10-10T17:44:11.326Z"
    }
  ],
  "nextCursor": null,
  "hasMore": false
}
```