> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clearpolicy.app/llms.txt
> Use this file to discover all available pages before exploring further.

# ClearPolicy REST API overview

> The ClearPolicy REST API communicates over HTTPS and returns JSON. Learn the base URL, versioning, pagination format, ID format, and error responses.

The ClearPolicy REST API gives you programmatic access to your organization's people, documents, and attestation requests. All endpoints communicate over HTTPS and return JSON.

## Base URL

```text theme={null}
https://api.clearpolicy.app/api/v1
```

The API path prefix (`/api/v1`) is included in every request URL. The current and only version is `v1`.

## Authentication

All endpoints require a valid API bearer token. Pass the token in the `Authorization` header:

```http theme={null}
Authorization: Bearer YOUR_ACCESS_TOKEN
```

See [Authentication](/api/authentication) for instructions on creating a token.

<Note>
  Your organization must have an active subscription or be within its trial period. If your trial has expired or your subscription is inactive, all API requests return a `402 Payment Required` response.
</Note>

## Access by role

API access follows your ClearPolicy role. Organization owners and administrators can create API tokens and use the people, documents, and attestation request endpoints. Tokens tied to Group Managers can use `GET /me` to confirm the token and organization, but other REST API endpoints return `403 Forbidden`.

## Response format

All responses are JSON. Successful responses return the requested resource or collection directly in the response body.

## IDs

All resource IDs are [ULIDs](https://github.com/ulid/spec) — lexicographically sortable string identifiers. They are represented as lowercase strings, for example:

```text theme={null}
01kg82xqfx6fvr046d15hnfmjv
```

## Pagination

List endpoints return paginated results. The response includes a `data` array alongside `links` and `meta` objects:

```json theme={null}
{
  "data": [...],
  "links": {
    "first": "https://api.clearpolicy.app/api/v1/people?page=1",
    "last": "https://api.clearpolicy.app/api/v1/people?page=5",
    "prev": null,
    "next": "https://api.clearpolicy.app/api/v1/people?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 5,
    "per_page": 25,
    "to": 25,
    "total": 120
  }
}
```

Use the `page` and `per_page` query parameters to navigate results. `per_page` accepts values between 1 and 100, and defaults to 25.

## Errors

Errors return JSON with an `error` field describing the problem:

```json theme={null}
{
  "error": "Person not found."
}
```

Common HTTP status codes:

| Status                     | Meaning                                                                                                  |
| -------------------------- | -------------------------------------------------------------------------------------------------------- |
| `200 OK`                   | Request succeeded.                                                                                       |
| `201 Created`              | Resource created successfully.                                                                           |
| `400 Bad Request`          | The request was invalid (e.g. document not published).                                                   |
| `401 Unauthorized`         | Missing or invalid access token.                                                                         |
| `402 Payment Required`     | Your organization's trial has expired or subscription is inactive. Visit your billing page to subscribe. |
| `403 Forbidden`            | Token lacks required permissions.                                                                        |
| `404 Not Found`            | The requested resource does not exist in your organization.                                              |
| `422 Unprocessable Entity` | Validation failed — check request parameters.                                                            |
| `429 Too Many Requests`    | Rate limit exceeded — wait and retry.                                                                    |

## Rate limiting

Each API token is limited to **60 requests per minute**. Limits apply per token, not per organization, so multiple tokens each have their own allowance.

If you exceed the limit, the API returns `429 Too Many Requests`. Responses include `Retry-After` and `X-RateLimit-*` headers so you can tell when to retry. Use exponential backoff when retrying.