Agent

The Agent endpoints let you ask questions over your project’s knowledge base. Three options depending on your use case: single query, chat, or batch.

POST /api/v2/agent/query

Single-shot Q&A. Ask one question, get one answer with source citations. Stateless — no conversation history is stored.

Authentication: Bearer token required

Request body:

Example request:

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 '{
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "query": "What are the fire safety requirements for this project?",
    "max_sources": 5
  }'

Example response 200 OK:

{
  "success": true,
  "data": {
    "answer": "Based on Section 3.1 of the Safety Management Plan, the project requires: (1) a documented fire safety plan reviewed quarterly, (2) fire extinguishers inspected monthly on every floor, (3) illuminated emergency exit signage, and (4) quarterly fire drills for all site personnel.",
    "sources": [
      {
        "id": "chunk_8f3a2b1c",
        "title": "Safety-Management-Plan-2026.pdf",
        "relevance": 0.94
      },
      {
        "id": "chunk_2d4e6f8a",
        "title": "HK-Fire-Safety-Code.pdf",
        "relevance": 0.87
      }
    ],
    "model": "gpt-4.1",
    "usage": {
      "prompt_tokens": 1450,
      "completion_tokens": 280,
      "total_tokens": 1730
    }
  },
  "request_id": "..."
}

POST /api/v2/chat

Multi-turn conversation. Send a message history and get a contextual response. The AI understands follow-up questions based on prior messages.

Authentication: Bearer token required

Request body:

Choosing the agent (chat_type)

• general / project — search your organization’s or project’s own documents. Always available.
• safety — the Safety Assistant, answering from the shared construction-safety corpus (regulations, PPE, site safety practice). Requires the Safety Assistant to be enabled for your organization; if it is not, the request returns 403 AGENT_NOT_ENABLED. project_id is not needed — the safety corpus is organization-independent.
• Omitted — the API classifies your message and routes it to the best agent among those enabled for your organization, falling back to general (document search) when nothing else fits. Integrations that know which agent they want should set chat_type explicitly; end-user chat boxes can omit it.

Example — asking the Safety Assistant directly:

curl -X POST https://api.pyramid-ai.com/api/v2/chat \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chat_type": "safety",
    "messages": [
      {"role": "user", "content": "What precautions are required for excavation works?"}
    ]
  }'

Example request:

curl -X POST https://api.pyramid-ai.com/api/v2/chat \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "messages": [
      {"role": "user", "content": "What are the fire safety requirements?"},
      {"role": "assistant", "content": "Based on the Safety Management Plan, the project requires quarterly fire drills, monthly extinguisher inspections, and illuminated exit signage."},
      {"role": "user", "content": "What about for buildings over 30 stories?"}
    ]
  }'

Example response 200 OK (when stream: false):

{
  "success": true,
  "data": {
    "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "message": {
      "role": "assistant",
      "content": "For buildings over 30 stories, the Fire Safety Code additionally requires..."
    },
    "sources": [
      {
        "id": "chunk_9x8y7z",
        "title": "HK-Fire-Safety-Code.pdf",
        "relevance": 0.91
      }
    ],
    "usage": {
      "prompt_tokens": 2100,
      "completion_tokens": 420,
      "total_tokens": 2520
    }
  },
  "request_id": "..."
}

Streaming: When stream: true, the response is delivered as Server-Sent Events (SSE). See Streaming & Async for implementation details.

POST /api/v2/agent/batches

Create a batch query. Submit multiple questions to be answered in the background. Ideal for compliance checklists, regulatory questionnaires, or bulk data extraction.

Authentication: Bearer token required

Request body:

Example request:

curl -X POST https://api.pyramid-ai.com/api/v2/agent/batches \
  -H "Authorization: Bearer pai_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "name": "Q2 Safety Compliance Checklist",
    "questions": [
      {"query": "Does the project have a documented fire safety plan?"},
      {"query": "Are emergency exits clearly marked on every floor?"},
      {"query": "Is there a monthly fire extinguisher inspection schedule?"}
    ]
  }'

Example response 201 Created:

{
  "success": true,
  "data": {
    "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
    "name": "Q2 Safety Compliance Checklist",
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "question_count": 3,
    "trigger_run_id": "run_abc123",
    "created_at": "2026-05-22T10:00:00Z"
  },
  "request_id": "..."
}

GET /api/v2/agent/batches

List all batch queries. Supports pagination and filtering by project.

Authentication: Bearer token required

Query parameters:

GET /api/v2/agent/batches/{id}

Get batch details with full results for each question.

Authentication: Bearer token required

Path parameters:

Example response 200 OK:

{
  "success": true,
  "data": {
    "id": "b1c2d3e4-f5a6-7890-bcde-f12345678901",
    "name": "Q2 Safety Compliance Checklist",
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "question_count": 3,
    "trigger_run_id": "run_abc123",
    "created_at": "2026-05-22T10:00:00Z",
    "questions": [
      {
        "id": "q1-uuid",
        "query": "Does the project have a documented fire safety plan?",
        "status": "completed",
        "answer": "Yes, the project includes a Fire Safety Management Plan (ref FSP-2026-01)...",
        "confidence": 0.91,
        "sources": null
      }
    ]
  },
  "request_id": "..."
}

GET /api/v2/agent/batches/{id}/export

Download batch results as a CSV file. Opens in Excel, Google Sheets, etc.

Authentication: Bearer token required

Path parameters:

Response: 200 OK with Content-Type: text/csv

CSV columns: