> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documents.pyramid-ai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server.

# API Reference

The Pyramid AI API is organized into three services, each serving a distinct purpose:

#### Pyramid Connect

Projects, documents, uploads, and processing.

#### Pyramid Agent

Chat, single queries, and batch Q\&A.

#### Pyramid Check

Compliance verification and analysis runs.

## API groups

| Group             | Prefix                 | Description                                    |
| ----------------- | ---------------------- | ---------------------------------------------- |
| **Agent**         | `/api/v2/agent`        | Single-shot queries and batch operations       |
| **Check**         | `/api/v2/check`        | Compliance verification and analysis runs      |
| **Documents**     | `/api/v2/documents`    | Upload, process, and manage documents          |
| **Organizations** | `/api/v2/organization` | Organization details for the authenticated key |
| **Projects**      | `/api/v2/projects`     | Create and manage knowledge projects           |

## Authentication

Every request (except `/health`) requires a Bearer token:

```bash
curl https://api.pyramid-ai.com/api/v2/projects \
  -H "Authorization: Bearer pai_live_YOUR_KEY"
```

See [Authentication](/authentication) for key management details.

## Response format

Every response follows the same envelope:

**`Success`**

```json title="Success"
{
  "success": true,
  "data": { ... },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**`Success with pagination`**

```json title="Success with pagination"
{
  "success": true,
  "data": [ ... ],
  "request_id": "...",
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 127
  }
}
```

**`Error`**

```json title="Error"
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "project_id is required",
    "field": "project_id"
  },
  "request_id": "..."
}
```

The `request_id` is also returned in the `X-Request-Id` header. Always include it when contacting support.

## Common status codes

| Status | Meaning          | Action                                    |
| ------ | ---------------- | ----------------------------------------- |
| `200`  | Success          | Process the response                      |
| `201`  | Created          | Resource created successfully             |
| `204`  | No Content       | Deletion successful                       |
| `400`  | Validation Error | Fix the request body/params               |
| `401`  | Unauthorized     | Check your API key                        |
| `403`  | Forbidden        | Feature not enabled or wrong org          |
| `404`  | Not Found        | Resource doesn't exist                    |
| `409`  | Conflict         | Duplicate or conflicting state            |
| `429`  | Rate Limited     | Wait and retry (see `Retry-After` header) |
| `500`  | Server Error     | Retry with exponential backoff            |

## Using the interactive explorer

The endpoints below include a built-in playground. To test:

1. Enter your API key in the **Authorization** field (use `Bearer pai_test_*` for staging)
2. Fill in the required parameters
3. Click **Send** to make a live request

> **Warning**
>
> The explorer sends real requests to the server you select. Use a `pai_test_*` key to avoid affecting production data.

## Versioning

All endpoints are under `/api/v2`. Breaking changes will increment the version number. Non-breaking additions (new optional fields, new endpoints) are added without a version bump.