Single-shot Q&A over project knowledge | Pyramid AI

curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/query \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "query": "What are the main compliance requirements?"
}'

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true,
  "data": {
    "answer": "Based on Section 3.1 of the Safety Management Plan, all workers must complete a site-specific induction before commencing work. The plan also requires daily toolbox talks covering the specific hazards",
    "sources": [
      {
        "id": "chunk_8f3a2b1c",
        "title": "Safety-Management-Plan-2026.pdf",
        "relevance": 0.94
      }
    ],
    "model": "gpt-4.1",
    "usage": {
      "prompt_tokens": 1450,
      "completion_tokens": 280,
      "total_tokens": 1730
    }
  },
  "pagination": {
    "total": 127,
    "offset": 0,
    "limit": 50
  }
}

curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/query \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "query": "What are the main compliance requirements?"
}'

{
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "success": true,
  "data": {
    "answer": "Based on Section 3.1 of the Safety Management Plan, all workers must complete a site-specific induction before commencing work. The plan also requires daily toolbox talks covering the specific hazards",
    "sources": [
      {
        "id": "chunk_8f3a2b1c",
        "title": "Safety-Management-Plan-2026.pdf",
        "relevance": 0.94
      }
    ],
    "model": "gpt-4.1",
    "usage": {
      "prompt_tokens": 1450,
      "completion_tokens": 280,
      "total_tokens": 1730
    }
  },
  "pagination": {
    "total": 127,
    "offset": 0,
    "limit": 50
  }
}

Stateless query endpoint — does not persist a chat history. Use this for one-off questions. For multi-turn conversation, use POST /chat instead.

Authentication

AuthorizationBearer

Pyramid API key (prefix with “Bearer ”)

Request

This endpoint expects an object.

project_idstringRequiredformat: "uuid"

querystringRequired<=100000 characters

max_sourcesintegerOptional1-20Defaults to 5

response_formatenumOptionalDefaults to text

Allowed values:

response_schemaobjectOptional

JSON schema for structured output (required when response_format=json)

search_scopeenumOptionalDefaults to project

Allowed values:

Response

Query result

request_idstringformat: "uuid"

Server-generated per-request UUID. Also sent as X-Request-Id response header. Include in support tickets.

successany

dataobject

paginationobject

Present only on list endpoints. Top-level (not nested inside data).

Errors

400

Bad Request Error

401

Unauthorized Error

$	curl -X POST https://api-staging.pyramid-ai.com/api/v2/agent/query \
>	-H "Authorization: Bearer <token>" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"project_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
>	"query": "What are the main compliance requirements?"
>	}'

1	{
2	"request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3	"success": true,
4	"data": {
5	"answer": "Based on Section 3.1 of the Safety Management Plan, all workers must complete a site-specific induction before commencing work. The plan also requires daily toolbox talks covering the specific hazards",
6	"sources": [
7	{
8	"id": "chunk_8f3a2b1c",
9	"title": "Safety-Management-Plan-2026.pdf",
10	"relevance": 0.94
11	}
12	],
13	"model": "gpt-4.1",
14	"usage": {
15	"prompt_tokens": 1450,
16	"completion_tokens": 280,
17	"total_tokens": 1730
18	}
19	},
20	"pagination": {
21	"total": 127,
22	"offset": 0,
23	"limit": 50
24	}
25	}