How-To Guides

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

ParameterDefaultDescription
max_sources5Number of source chunks to return (1-20)
search_scopeprojectSearch project documents only, or entire org

Run a batch of questions

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

1

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.

2

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.

3

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

ParameterDescription
question_templateTemplate 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