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

# Pecta REST API: endpoints, auth, and errors

> Complete reference for the Pecta REST API. Authenticate with a Bearer token, call endpoints under https://api.pecta.ai, and receive JSON responses.

The Pecta REST API lets you run cloud-side gate evaluations, ingest batched telemetry, query evaluation events, and fetch agent reputation scores over standard HTTP. All endpoints live under `https://api.pecta.ai` and require an `Authorization: Bearer <key>` header on every `/v1/*` route.

## Base URL

```
https://api.pecta.ai
```

## Endpoints

| Method | Path                                                   | Description                                          |
| ------ | ------------------------------------------------------ | ---------------------------------------------------- |
| `POST` | [`/v1/evaluate`](/api-reference/evaluate)              | Run cloud gate evaluation on an agent output         |
| `POST` | [`/v1/ingest`](/api-reference/ingest)                  | Ingest a batch of telemetry events from SDK or proxy |
| `GET`  | [`/v1/events`](/api-reference/events)                  | List paginated evaluation events for your org        |
| `GET`  | [`/v1/reputation/:agentId`](/api-reference/reputation) | Fetch the current reputation score for an agent      |
| `GET`  | [`/v1/agents`](/api-reference/agents)                  | List all agents registered to your org               |
| `POST` | [`/v1/agents`](/api-reference/agents)                  | Register an agent explicitly                         |
| `GET`  | `/health`                                              | Health check — no auth required                      |

## Authentication

Every `/v1/*` request must include your API key in the `Authorization` header:

```bash theme={null}
Authorization: Bearer pk_live_<your-key>
```

Pecta issues two key types — `pk_live_` (publishable) and `sk_live_` (secret). Use `pk_live_` for reads and client-visible configs; use `sk_live_` for server-to-server calls. See the [Authentication](/api-reference/authentication) page for full details.

## Error format

All error responses share the same shape:

```json theme={null}
{
  "error": "human-readable message",
  "code": "machine_readable_code",
  "status": 401
}
```

Common codes:

| HTTP status | Code               | Meaning                               |
| ----------- | ------------------ | ------------------------------------- |
| `400`       | `validation_error` | Request body failed schema validation |
| `400`       | `bad_json`         | Request body is not valid JSON        |
| `401`       | `auth_missing`     | No `Authorization` header present     |
| `401`       | `auth_invalid`     | Key not found                         |
| `401`       | `auth_revoked`     | Key has been revoked                  |
| `401`       | `hmac_invalid`     | HMAC signature does not match         |
| `429`       | `rate_limited`     | Rate limit exceeded — see below       |

## Rate limiting

Pecta applies per-org, per-minute rate limits on a rolling 60-second window.

| Endpoint                 | Limit                 |
| ------------------------ | --------------------- |
| `POST /v1/ingest`        | 500 requests / minute |
| All other `/v1/*` routes | 200 requests / minute |

When you exceed the limit the API returns `429` with a `Retry-After` header indicating how many seconds to wait before retrying.

```json theme={null}
{
  "error": "rate limit exceeded",
  "code": "rate_limited",
  "status": 429
}
```