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

# Knowledge & Search

## How Pyramid AI answers questions

When you ask a question through the Agent API, the AI doesn't just make up an answer — it **searches your actual documents** first, finds the most relevant passages, and then formulates a response grounded in that evidence.

This approach is called **Retrieval Augmented Generation (RAG)**. In plain terms:

1. **Retrieval** — find the most relevant document sections
2. **Augmented** — feed those sections to the AI as context
3. **Generation** — the AI writes an answer based on what it found

```
Your question
        │
        ▼
┌───────────────┐     ┌───────────────┐     ┌───────────────┐
│ Search your   │ ──> │ Feed context  │ ──> │ AI generates  │
│ document      │     │ to the AI     │     │ an answer     │
│ chunks        │     │ model         │     │ with citations│
└───────────────┘     └───────────────┘     └───────────────┘
        │                                           │
        ▼                                           ▼
 "Found 5 relevant                         "Based on Section 3.2
  passages from                              of the Safety Plan..."
  3 documents"
```

## Why this matters

Traditional search finds pages containing your keywords. Pyramid AI understands **meaning**.

| You ask                  | Keyword search finds   | Pyramid AI finds                                                                                       |
| ------------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------ |
| "What PPE is required?"  | Pages mentioning "PPE" | Sections about safety equipment, protective gear, hard hats — even if they never use the acronym "PPE" |
| "Fire exit requirements" | Pages with "fire exit" | Building code sections about emergency egress, evacuation routes, and fire door specifications         |

## Sources and citations

Every response includes a `sources` array that tells you exactly where the answer came from:

```json
{
  "answer": "According to the project safety plan, all workers must wear...",
  "sources": [
    {
      "id": "chunk_abc",
      "title": "Safety-Plan-2026.pdf",
      "relevance": 0.95
    },
    {
      "id": "chunk_def",
      "title": "HK-Building-Regulations.pdf",
      "relevance": 0.87
    }
  ]
}
```

| Field       | What it tells you                                      |
| ----------- | ------------------------------------------------------ |
| `title`     | Which document the information came from               |
| `relevance` | How closely the passage matches your question (0 to 1) |

This traceability is critical for compliance — you can always verify the AI's answer against the original source document.

## Three ways to search

Pyramid AI offers three interfaces for querying your knowledge base, each designed for different use cases:

### 1. Single Query — `POST /api/v2/agent/query`

Ask one question, get one answer. No conversation history, no session state. The simplest integration point.

**Best for:** Excel add-ins, automated scripts, one-off lookups, embedding answers in other tools.

```json
{
  "project_id": "...",
  "query": "What is the maximum allowable floor load?"
}
```

### 2. Chat — `POST /api/v2/chat`

Multi-turn conversations where the AI remembers what was discussed. Follow-up questions understand context from earlier in the conversation.

**Best for:** Chatbots, interactive assistants, exploratory research where users drill into a topic.

```json
{
  "project_id": "...",
  "messages": [
    { "role": "user", "content": "What are the fire safety requirements?" },
    { "role": "assistant", "content": "According to..." },
    { "role": "user", "content": "What about for buildings over 30 stories?" }
  ]
}
```

The AI understands that "What about for buildings over 30 stories?" refers to fire safety requirements from the previous message.

### 3. Batch Queries — `POST /api/v2/agent/batches`

Submit hundreds of questions at once and get them all answered in the background. Results are downloadable as CSV.

**Best for:** Compliance questionnaires, regulatory checklists, bulk data extraction, audit preparation.

```json
{
  "project_id": "...",
  "name": "Q2 Safety Checklist",
  "questions": [
    "Is there a fire safety plan?",
    "Are emergency exits marked?",
    "Is PPE policy documented?",
    "..."
  ]
}
```

## Search scope

The AI only searches documents within the **project** you specify. This is intentional — it keeps results focused and prevents cross-contamination between unrelated projects.

If you need to search across multiple projects, make separate queries to each project.

## Beyond your own documents

Two other knowledge sources are available on the chat endpoint besides your project and organization documents:

* **Open Library** — the shared Hong Kong government corpus (circulars, practice notes, press releases). Select it with `search_scope: "open_library"` (requires the `api.open_library` feature).
* **Safety Assistant** — a shared construction-safety corpus (regulations, PPE, site safety practice). Select it with `chat_type: "safety"` (requires the Safety Assistant to be enabled for your organization; otherwise the request returns `403 AGENT_NOT_ENABLED`).

When you omit `chat_type`, chat picks the best agent for the message automatically from those enabled for your organization. See the [Agent endpoint reference](/api-reference/agent) for details.

## Tips for better results

* **Be specific** — "What is the maximum concrete pour temperature?" gets better results than "Tell me about concrete"
* **Upload relevant documents** — the AI can only find what's in your project. Missing documents mean missing answers
* **Use complete documents** — partial uploads or corrupted files lead to incomplete indexing
* **Check document status** — only `completed` documents are searchable. Documents still `processing` won't appear in results