> 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.

# Projects

Projects are top-level containers that group related documents together. Every document, query, and compliance check is scoped to a project.

---

## POST /api/v2/projects

Creates a new empty project.

**Authentication:** Bearer token required

**Request body:**

| Field         | Type   | Required | Description                                   |
| ------------- | ------ | -------- | --------------------------------------------- |
| `name`        | string | Yes      | Project name (1–200 characters)               |
| `description` | string | No       | Optional description of the project's purpose |

**Example request:**

```bash
curl -X POST https://api.pyramid-ai.com/api/v2/projects \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project"
  }'
```

**Example response** `201 Created`:

```json
{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 0,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T10:00:00Z"
  },
  "request_id": "550e8400-e29b-41d4-a716-446655440000"
}
```

**Error responses:**

| Status | Code               | When                       |
| ------ | ------------------ | -------------------------- |
| `400`  | `VALIDATION_ERROR` | Missing or invalid `name`  |
| `401`  | `UNAUTHORIZED`     | Missing or invalid API key |

---

## GET /api/v2/projects

Returns all projects for the authenticated organization. Supports pagination.

**Authentication:** Bearer token required

**Query parameters:**

| Parameter | Type    | Default | Description                        |
| --------- | ------- | ------- | ---------------------------------- |
| `limit`   | integer | 50      | Maximum results per page (max 200) |
| `offset`  | integer | 0       | Number of results to skip          |

**Example request:**

```bash
curl https://api.pyramid-ai.com/api/v2/projects?limit=10&offset=0 \
  -H "Authorization: Bearer pai_live_YOUR_KEY"
```

**Example response** `200 OK`:

```json
{
  "success": true,
  "data": [
    {
      "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
      "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
      "name": "Marina Bay Tower - Safety Docs",
      "description": "All safety and compliance documents for the Marina Bay Tower project",
      "document_count": 42,
      "created_at": "2026-05-22T10:00:00Z",
      "updated_at": "2026-05-22T14:30:00Z"
    }
  ],
  "request_id": "...",
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 1
  }
}
```

---

## GET /api/v2/projects/\{id}

Returns details for a single project.

**Authentication:** Bearer token required

**Path parameters:**

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id`      | uuid | Project ID  |

**Example request:**

```bash
curl https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY"
```

**Example response** `200 OK`:

```json
{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - Safety Docs",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 42,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T14:30:00Z"
  },
  "request_id": "..."
}
```

**Error responses:**

| Status | Code           | When                                                          |
| ------ | -------------- | ------------------------------------------------------------- |
| `401`  | `UNAUTHORIZED` | Missing or invalid API key                                    |
| `404`  | `NOT_FOUND`    | Project does not exist or belongs to a different organization |

---

## PATCH /api/v2/projects/\{id}

Updates a project's name and/or description. Only the fields you include are changed.

**Authentication:** Bearer token required

**Path parameters:**

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id`      | uuid | Project ID  |

**Request body:**

| Field         | Type   | Required | Description                                            |
| ------------- | ------ | -------- | ------------------------------------------------------ |
| `name`        | string | No       | New project name (1–200 characters)                    |
| `description` | string | No       | New description (max 500 characters, or null to clear) |

At least one field must be provided.

**Example request:**

```bash
curl -X PATCH https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marina Bay Tower - All Documents"}'
```

**Example response** `200 OK`:

```json
{
  "success": true,
  "data": {
    "id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "name": "Marina Bay Tower - All Documents",
    "description": "All safety and compliance documents for the Marina Bay Tower project",
    "document_count": 42,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T15:00:00Z"
  },
  "request_id": "..."
}
```

---

## DELETE /api/v2/projects/\{id}

Permanently deletes a project. The project must have **zero documents** — delete all documents first, or the request will fail with `409`.

**Authentication:** Bearer token required

**Path parameters:**

| Parameter | Type | Description |
| --------- | ---- | ----------- |
| `id`      | uuid | Project ID  |

**Example request:**

```bash
curl -X DELETE https://api.pyramid-ai.com/api/v2/projects/7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f \
  -H "Authorization: Bearer pai_live_YOUR_KEY"
```

**Response** `204 No Content` — no response body.

**Error responses:**

| Status | Code           | When                                           |
| ------ | -------------- | ---------------------------------------------- |
| `401`  | `UNAUTHORIZED` | Missing or invalid API key                     |
| `404`  | `NOT_FOUND`    | Project does not exist                         |
| `409`  | `CONFLICT`     | Project still has documents. Delete them first |

**Response fields (all endpoints):**

| Field            | Type           | Description                                   |
| ---------------- | -------------- | --------------------------------------------- |
| `id`             | uuid           | Unique project identifier                     |
| `org_id`         | string         | Organization the project belongs to           |
| `name`           | string         | Project name                                  |
| `description`    | string \| null | Project description                           |
| `document_count` | integer        | Number of documents in the project            |
| `created_at`     | string         | When the project was created (ISO 8601)       |
| `updated_at`     | string         | When the project was last modified (ISO 8601) |