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

# Public API

> Authentication, scopes, resources, and best practices for using the Acrity public API.

The Acrity public API lets you query workspace context, repositories, pull requests, reviews, webhooks, credentials, bootstrap, and security scans according to the API key scopes.

## Base

Public routes use the `/api/v1` prefix. OpenAPI documentation is available in the Acrity environment at:

* `/docs`, for interactive viewing;
* `/openapi/v1-public.json`, for tool consumption;
* localized variants when enabled, such as `/openapi/v1-public.pt-BR.json`.

## Authentication

Use the `X-Acrity-Key` header:

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/context"
```

API keys are created under `API Keys`. Creating an API key requires a Workspace admin (platform admins also have access).

## Scopes

| Family         | Read                 | Write                 |
| -------------- | -------------------- | --------------------- |
| Reviews        | `Reviews.Read`       | `Reviews.Write`       |
| Repositories   | `Repositories.Read`  | `Repositories.Write`  |
| Credentials    | `Credentials.Read`   | `Credentials.Write`   |
| Webhooks       | `Webhooks.Read`      | `Webhooks.Write`      |
| Workspaces     | `Workspaces.Read`    | `Workspaces.Write`    |
| Security scans | `SecurityScans.Read` | `SecurityScans.Write` |

Prefer one API key per consuming system. This makes rotation, audit, and scope limitation easier.

## Main resources

| Resource       | Common use                                                                           |
| -------------- | ------------------------------------------------------------------------------------ |
| Context        | validate API key, workspace, and visible scopes                                      |
| Repositories   | list, view status, and manage authorized connections                                 |
| Pull requests  | find changes reviewed by Acrity                                                      |
| Reviews        | list history, view findings, and request review when allowed                         |
| Webhooks       | create, list, view, update, and enable or disable outbound webhooks (no hard delete) |
| Workspaces     | view workspace information and health                                                |
| Credentials    | view metadata and manage authorized credentials                                      |
| Bootstrap      | check eligibility and track architecture guidance generation                         |
| Security scans | list, view, and start dependency scans                                               |

## Pagination and filters

Listings can use pagination and filters. See your environment's OpenAPI specification for exact parameters for each resource.

The default page size is 20 and the maximum is 50. A request with a page size above 50 returns `400`.

Best practices:

* use small pages in recurring integrations;
* keep the cursor or processed page in the automation;
* treat empty responses as a valid state;
* apply backoff on `429`.

## Errors

| Status | Meaning                                            |
| ------ | -------------------------------------------------- |
| `400`  | invalid request                                    |
| `401`  | API key missing, invalid, expired, or inactive     |
| `403`  | API key is valid, but lacks required scope         |
| `404`  | resource not found or not visible to the workspace |
| `409`  | conflict with current resource state               |
| `429`  | usage limit reached                                |
| `5xx`  | temporary error or unavailability                  |

## Rate limits

Each API key is limited to about 300 requests per minute by default. When you exceed the limit, the API returns `429` along with these response headers:

| Header                  | Meaning                                  |
| ----------------------- | ---------------------------------------- |
| `Retry-After`           | seconds to wait before retrying          |
| `X-RateLimit-Limit`     | requests allowed per window              |
| `X-RateLimit-Remaining` | requests remaining in the current window |
| `X-RateLimit-Reset`     | time when the current window resets      |

Honor `Retry-After` and apply backoff before retrying.

## Example call

```bash theme={null}
curl \
  -H "X-Acrity-Key: acr_live_..." \
  "https://acrity.io/api/v1/repositories?page=1&pageSize=25"
```

<Tip>
  Start with `/api/v1/context` when diagnosing an integration. This call confirms whether the key is active and which scopes are available.
</Tip>