Agent

Single-shot queries, multi-turn chat, and batch processing

Agent

Single-shot queries, multi-turn chat, and batch processing

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:

Field	Type	Required	Description
`project_id`	uuid	Yes	Which project’s documents to search
`query`	string	Yes	The question to ask (max 100,000 characters)
`max_sources`	integer	No	Number of sources to return (1–20, default 5)
`search_scope`	string	No	`project` (default) or `org` to search all org knowledge
`response_format`	string	No	`text` (default) or `json` for structured output
`response_schema`	object	No	JSON schema (required when `response_format` is `json`)

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:

1 {
2   "success": true,
3   "data": {
4     "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.",
5     "sources": [
6       {
7         "id": "chunk_8f3a2b1c",
8         "title": "Safety-Management-Plan-2026.pdf",
9         "relevance": 0.94
10       },
11       {
12         "id": "chunk_2d4e6f8a",
13         "title": "HK-Fire-Safety-Code.pdf",
14         "relevance": 0.87
15       }
16     ],
17     "model": "gpt-4.1",
18     "usage": {
19       "prompt_tokens": 1450,
20       "completion_tokens": 280,
21       "total_tokens": 1730
22     }
23   },
24   "request_id": "..."
25 }

Field	Type	Description
`answer`	string	AI-generated answer grounded in project documents
`sources`	array	Document chunks referenced in the answer
`sources[].id`	string	Chunk identifier
`sources[].title`	string	Source document file name
`sources[].relevance`	number	Semantic similarity score (0 to 1)
`model`	string	AI model used
`usage`	object	Token consumption for billing

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:

Field	Type	Required	Description
`messages`	array	Yes	Conversation history (1–50 messages)
`messages[].role`	string	Yes	`user`, `assistant`, or `system`
`messages[].content`	string	Yes	Message text
`project_id`	uuid	No	Project to search for grounded answers
`chat_id`	uuid	No	Provide to continue an existing chat. Omit to start new
`model`	string	No	`chat-model` (default) or `chat-model-reasoning` (slower, more thorough)
`stream`	boolean	No	`true` for real-time SSE streaming (default `false`)

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

1 {
2   "success": true,
3   "data": {
4     "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "message": {
6       "role": "assistant",
7       "content": "For buildings over 30 stories, the Fire Safety Code additionally requires..."
8     },
9     "sources": [
10       {
11         "id": "chunk_9x8y7z",
12         "title": "HK-Fire-Safety-Code.pdf",
13         "relevance": 0.91
14       }
15     ],
16     "usage": {
17       "prompt_tokens": 2100,
18       "completion_tokens": 420,
19       "total_tokens": 2520
20     }
21   },
22   "request_id": "..."
23 }

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:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to query against
`name`	string	Yes	Batch name (1–200 characters)
`questions`	array	Yes	Array of question objects (1–500)
`questions[].query`	string	Yes	The question text
`questions[].metadata`	object	No	Optional metadata to attach to this question
`question_template`	string	No	Template with `{input}` placeholder applied to each question

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:

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

GET /api/v2/agent/batches

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

Authentication: Bearer token required

Query parameters:

Parameter	Type	Default	Description
`project_id`	uuid	—	Filter by project
`limit`	integer	50	Maximum results (max 200)
`offset`	integer	0	Results to skip

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

Get batch details with full results for each question.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Batch ID

Example response 200 OK:

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

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:

Parameter	Type	Description
`id`	uuid	Batch ID

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

CSV columns:

Column	Description
`question_id`	Unique question identifier
`question`	The question text
`answer`	AI-generated answer
`confidence`	Confidence score (0 to 1)
`sources`	Source citations

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:

Field	Type	Required	Description
`project_id`	uuid	Yes	Which project’s documents to search
`query`	string	Yes	The question to ask (max 100,000 characters)
`max_sources`	integer	No	Number of sources to return (1–20, default 5)
`search_scope`	string	No	`project` (default) or `org` to search all org knowledge
`response_format`	string	No	`text` (default) or `json` for structured output
`response_schema`	object	No	JSON schema (required when `response_format` is `json`)

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:

1 {
2   "success": true,
3   "data": {
4     "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.",
5     "sources": [
6       {
7         "id": "chunk_8f3a2b1c",
8         "title": "Safety-Management-Plan-2026.pdf",
9         "relevance": 0.94
10       },
11       {
12         "id": "chunk_2d4e6f8a",
13         "title": "HK-Fire-Safety-Code.pdf",
14         "relevance": 0.87
15       }
16     ],
17     "model": "gpt-4.1",
18     "usage": {
19       "prompt_tokens": 1450,
20       "completion_tokens": 280,
21       "total_tokens": 1730
22     }
23   },
24   "request_id": "..."
25 }

Field	Type	Description
`answer`	string	AI-generated answer grounded in project documents
`sources`	array	Document chunks referenced in the answer
`sources[].id`	string	Chunk identifier
`sources[].title`	string	Source document file name
`sources[].relevance`	number	Semantic similarity score (0 to 1)
`model`	string	AI model used
`usage`	object	Token consumption for billing

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:

Field	Type	Required	Description
`messages`	array	Yes	Conversation history (1–50 messages)
`messages[].role`	string	Yes	`user`, `assistant`, or `system`
`messages[].content`	string	Yes	Message text
`project_id`	uuid	No	Project to search for grounded answers
`chat_id`	uuid	No	Provide to continue an existing chat. Omit to start new
`model`	string	No	`chat-model` (default) or `chat-model-reasoning` (slower, more thorough)
`stream`	boolean	No	`true` for real-time SSE streaming (default `false`)

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

1 {
2   "success": true,
3   "data": {
4     "chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "message": {
6       "role": "assistant",
7       "content": "For buildings over 30 stories, the Fire Safety Code additionally requires..."
8     },
9     "sources": [
10       {
11         "id": "chunk_9x8y7z",
12         "title": "HK-Fire-Safety-Code.pdf",
13         "relevance": 0.91
14       }
15     ],
16     "usage": {
17       "prompt_tokens": 2100,
18       "completion_tokens": 420,
19       "total_tokens": 2520
20     }
21   },
22   "request_id": "..."
23 }

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:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to query against
`name`	string	Yes	Batch name (1–200 characters)
`questions`	array	Yes	Array of question objects (1–500)
`questions[].query`	string	Yes	The question text
`questions[].metadata`	object	No	Optional metadata to attach to this question
`question_template`	string	No	Template with `{input}` placeholder applied to each question

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:

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

GET /api/v2/agent/batches

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

Authentication: Bearer token required

Query parameters:

Parameter	Type	Default	Description
`project_id`	uuid	—	Filter by project
`limit`	integer	50	Maximum results (max 200)
`offset`	integer	0	Results to skip

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

Get batch details with full results for each question.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Batch ID

Example response 200 OK:

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

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:

Parameter	Type	Description
`id`	uuid	Batch ID

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

CSV columns:

Column	Description
`question_id`	Unique question identifier
`question`	The question text
`answer`	AI-generated answer
`confidence`	Confidence score (0 to 1)
`sources`	Source citations

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

1	{
2	"success": true,
3	"data": {
4	"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.",
5	"sources": [
6	{
7	"id": "chunk_8f3a2b1c",
8	"title": "Safety-Management-Plan-2026.pdf",
9	"relevance": 0.94
10	},
11	{
12	"id": "chunk_2d4e6f8a",
13	"title": "HK-Fire-Safety-Code.pdf",
14	"relevance": 0.87
15	}
16	],
17	"model": "gpt-4.1",
18	"usage": {
19	"prompt_tokens": 1450,
20	"completion_tokens": 280,
21	"total_tokens": 1730
22	}
23	},
24	"request_id": "..."
25	}

1	{
2	"success": true,
3	"data": {
4	"chat_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5	"message": {
6	"role": "assistant",
7	"content": "For buildings over 30 stories, the Fire Safety Code additionally requires..."
8	},
9	"sources": [
10	{
11	"id": "chunk_9x8y7z",
12	"title": "HK-Fire-Safety-Code.pdf",
13	"relevance": 0.91
14	}
15	],
16	"usage": {
17	"prompt_tokens": 2100,
18	"completion_tokens": 420,
19	"total_tokens": 2520
20	}
21	},
22	"request_id": "..."
23	}

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