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

$
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

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

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)

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:

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.