Skip to navigation
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?"
  }'
{
  "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

ParameterDefaultDescription
max_sources5Number of source chunks to return (1-20)
search_scopeprojectproject (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.

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.

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