Query Your Knowledge Base

Ask questions, run batch queries, and export results

Query Your Knowledge Base

Ask questions, run batch queries, and export results

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)
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:

$ 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?"
>   }'

1 {
2   "success": true,
3   "data": {
4     "answer": "According to the safety manual, confined space entry requires...",
5     "sources": [
6       {
7         "id": "chunk_abc",
8         "title": "safety-manual.pdf",
9         "relevance": 0.95
10       }
11     ],
12     "model": "gpt-4.1",
13     "usage": {
14       "prompt_tokens": 1200,
15       "completion_tokens": 350
16     }
17   },
18   "request_id": "..."
19 }

Options

Parameter	Default	Description
`max_sources`	`5`	Number of source chunks to return (1-20)
`search_scope`	`project`	Search `project` documents only, or entire `org`

Run a batch of questions

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

Create the batch

$ 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:

$ 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:

$ 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

$ # 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 — verify requirements against documents
View Your Organization — check your org details and settings