> 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 & Documents

## The big picture

Everything in Pyramid AI starts with two building blocks: **projects** and **documents**.

```
Organization (your company)
  └── Project (a job site, a tender, a department)
        └── Document (a PDF, Word doc, or web page)
              └── Chunks (searchable pieces the AI reads)
```

Think of it like a filing system:

* Your **organization** is the office
* **Projects** are the filing cabinets — one per job, tender, or topic
* **Documents** are the files inside each cabinet
* **Chunks** are the individual pages the AI actually reads when answering questions

## Projects

A project is a container that groups related documents together. When you ask a question or run a compliance check, you always specify which project to search — the AI only looks at documents in that project.

**Why projects matter:**

* A question about "fire safety requirements" will give different answers depending on whether you're searching a Hong Kong construction project or a Saudi residential project
* Projects keep knowledge isolated so answers are always relevant to the right context

### Creating a project

```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",
    "description": "Safety and compliance docs for the Marina Bay project"
  }'
```

### Key properties

| Field            | Description                                            |
| ---------------- | ------------------------------------------------------ |
| `id`             | Unique identifier (UUID) — used in all other API calls |
| `name`           | Human-readable project name                            |
| `description`    | Optional context about what this project contains      |
| `document_count` | Number of documents uploaded to this project           |
| `created_at`     | When the project was created                           |

> **Note**
>
> Deleting a project requires removing all its documents first. This prevents accidental data loss.

## Documents

A document is any file you upload to a project. Once uploaded and processed, the AI can search through it to answer questions, verify compliance, and power chat conversations.

### Supported file types

| Type           | Extensions                         |
| -------------- | ---------------------------------- |
| PDF            | `.pdf`                             |
| Microsoft Word | `.doc`, `.docx`                    |
| Plain text     | `.txt`                             |
| Web content    | Scraped via platform (not API yet) |

### Document lifecycle

Every document goes through a series of states from upload to ready:

```
Reserve upload slot ──> Upload file bytes ──> Trigger processing
                                                     │
                                          ┌──────────┴──────────┐
                                          ▼                     ▼
                                        ready                failed
                                    (searchable)         (check error_message)
```

| Status                | What it means                                              |
| --------------------- | ---------------------------------------------------------- |
| `awaiting_upload`     | Upload slot reserved, waiting for file bytes               |
| `processing`          | AI is extracting text, splitting into chunks, and indexing |
| `completed` / `ready` | Document is fully processed and searchable                 |
| `failed`              | Something went wrong — check `error_message` for details   |

> **Warning**
>
> Documents are only searchable after reaching `completed` status. Queries against a project with documents still processing will not include those documents in results.

## Chunks — what the AI actually reads

When a document is processed, Pyramid splits it into **chunks** — small, overlapping sections of text (typically a few paragraphs each). This is how the AI finds relevant information quickly without reading the entire document every time.

When you get a response from the Agent or Check APIs, the `sources` array tells you exactly which chunks were used — including the document name and the specific section.

You don't manage chunks directly. They're created automatically during processing and cleaned up when a document is deleted.

## How they connect

Here's how a typical flow works, from project creation to getting answers:

#### Create a project

`POST /api/v2/projects` — gives you a `project_id`

#### Upload documents

`POST /api/v2/documents` → upload file → `POST /api/v2/documents/process`

#### Wait for processing

`GET /api/v2/documents/{id}` — poll until status is `completed`

#### Query or check

Use the `project_id` with Agent (`/agent/query`, `/chat`) or Check (`/check/verify`, `/check/runs`) endpoints

## Common patterns

### One project per job site

Most construction clients create one project per physical site or contract. All handbooks, method statements, and safety documents for that site go into one project.

### Shared organization documents

Some documents (like company-wide safety policies) apply to every project. Upload these to each relevant project, or use the platform UI to manage organization-level documents.

### Multiple projects for different purposes

A compliance team might create separate projects for different standards:

* "HK Building Regulations" — all Hong Kong construction codes
* "Marina Bay Tower" — site-specific documents
* "Company Safety Policy" — internal standards

Then run compliance checks against the appropriate project depending on what they're verifying.