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

# Query Your Knowledge Base

## Before you begin

* You have an API key (`pai_test_*` or `pai_live_*`)
* You have a project with at least one document in `ready` status ([Upload Documents](/howto/documents))
* Feature `api.query` is enabled for your organization (plus `api.batches` for batch operations)

## Ask a single question

Send a question and get an answer grounded in your project's documents:

```bash
curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/query \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "query": "What PPE is required for confined space entry?"
  }'
```

```json
{
  "success": true,
  "data": {
    "answer": "According to the safety manual, confined space entry requires...",
    "sources": [
      {
        "id": "chunk_abc",
        "title": "safety-manual.pdf",
        "relevance": 0.95
      }
    ],
    "model": "gpt-4.1",
    "usage": {
      "prompt_tokens": 1200,
      "completion_tokens": 350
    }
  },
  "request_id": "..."
}
```

### Options

| Parameter      | Default   | Description                                                                                                        |
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------ |
| `max_sources`  | `5`       | Number of source chunks to return (1-20)                                                                           |
| `search_scope` | `project` | `project` (requires `project_id`), `org` for organization documents, or `open_library` for the Open Library corpus |

### Query the Open Library

With `search_scope: open_library`, the Agent answers from the Open Library, a corpus of Hong Kong government engineering documents (technical circulars, standards, practice notes, publications). Omit `project_id`; sources in the response carry a `url` field pointing at the public document. This scope requires the `api.open_library` feature on your organization. Contact support to enable it.

```bash
curl -X POST https://api.pyramid-ai.com/api/v2/agent/query \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What do technical circulars say about site safety supervision?",
    "search_scope": "open_library"
  }'
```

## Run a batch of questions

Submit multiple questions for async processing — useful for spreadsheet workflows or bulk analysis.

#### Create the batch

```bash
curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/batches \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "YOUR_PROJECT_ID",
    "name": "Tree Survey Review",
    "questions": [
      {"query": "Should Tree #101 (Banyan) be retained or removed?"},
      {"query": "Should Tree #102 (Palm) be retained or removed?"},
      {"query": "Should Tree #103 (Ficus) be retained or removed?"}
    ]
  }'
```

The API returns immediately with a batch ID. Processing happens in the background.

#### Check batch status

Poll the batch to see progress:

```bash
curl https://api-staging.pyramid-ai.com/api/v2/agent/batches/BATCH_ID \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"
```

The response includes each question and its answer once processed.

#### Export results as CSV

When the batch is complete, download results as a CSV file:

```bash
curl https://api-staging.pyramid-ai.com/api/v2/agent/batches/BATCH_ID/export \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE" \
  -o results.csv
```

The CSV contains columns: `question_id`, `question`, `answer`, `confidence`, `sources`.

### Batch options

| Parameter           | Description                                                                                                                             |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `question_template` | Template with `{input}` placeholder applied to each question. e.g. `"Based on the tree survey, should {input} be retained or removed?"` |

## List batches

```bash
# All batches
curl https://api-staging.pyramid-ai.com/api/v2/agent/batches \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"

# Filter by project
curl "https://api-staging.pyramid-ai.com/api/v2/agent/batches?project_id=YOUR_PROJECT_ID" \
  -H "Authorization: Bearer pai_test_YOUR_KEY_HERE"
```

## What's next

* [Run a Compliance Check](/howto/check) — verify requirements against documents
* [View Your Organization](/howto/organizations) — check your org details and settings