Check

Compliance verification and analysis runs

Check

Compliance verification and analysis runs

The Check endpoints verify whether your project documents satisfy specific requirements. Two approaches: quick single-requirement verification, or structured multi-requirement audit runs.

POST /api/v2/check/verify

Verify a single compliance requirement. Synchronous — returns a verdict immediately. Can take up to 5 minutes for complex requirements.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to check against
`requirement`	string	Yes	The requirement to verify (max 5,000 characters)
`handbook_ids`	uuid[]	No	Limit check to specific handbooks. Omit to use all project knowledge

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/verify \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
>     "requirement": "All electrical installations must comply with AS/NZS 3000 wiring standards"
>   }'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "verdict": "COMPLIANT",
5     "confidence": 0.92,
6     "evidence": "Section 4.2 of the Electrical Safety Specification states: 'All wiring installations shall comply with AS/NZS 3000:2018 including amendments.'",
7     "explanation": "The project documentation explicitly references compliance with AS/NZS 3000 in the Electrical Safety Specification. The specification mandates that all subcontractors certify their work against this standard.",
8     "recommendation": null,
9     "sources": [
10       {
11         "handbook_id": "hb-uuid-1",
12         "node_id": "node-uuid-1",
13         "title": "Electrical-Safety-Specification.pdf",
14         "start_page": 8,
15         "end_page": 9
16       }
17     ],
18     "handbook": {
19       "id": "hb-uuid-1",
20       "name": "Electrical Safety Specification"
21     }
22   },
23   "request_id": "..."
24 }

Response fields:

Field	Type	Description
`verdict`	string	`COMPLIANT`, `CONTRADICTS`, or `NOT_FOUND`
`confidence`	number	How certain the AI is (0 to 1). Below 0.7 suggests insufficient evidence
`evidence`	string	Verbatim quote from the source document supporting the verdict
`explanation`	string	Plain-language reasoning for the decision
`recommendation`	string \| null	Suggested action if non-compliant. Null if compliant
`sources`	array	Documents and pages referenced
`sources[].title`	string	Source document name
`sources[].start_page`	integer \| null	Starting page of the relevant section
`sources[].end_page`	integer \| null	Ending page of the relevant section
`handbook`	object	Which handbook was checked against

Verdict values:

Verdict	Meaning
`COMPLIANT`	Requirement is satisfied by project documentation
`CONTRADICTS`	Project documentation contradicts the requirement
`NOT_FOUND`	No evidence for or against — documents may not cover this topic

POST /api/v2/check/runs

Create a compliance check run. Define a set of requirements to check as a batch. Does not start processing — call the trigger endpoint when ready.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to check against
`name`	string	Yes	Run name (e.g., “Q2 2026 Fire Safety Audit”)
`requirements`	array	Yes	Array of requirement objects (1–1,000)
`requirements[].text`	string	Yes	Requirement text (max 5,000 characters)
`requirements[].metadata`	object	No	Optional metadata
`handbook_ids`	uuid[]	No	Limit check to specific handbooks

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/runs \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
>     "name": "Q2 2026 Fire Safety Audit",
>     "requirements": [
>       {"text": "The site must have a documented fire safety plan"},
>       {"text": "Fire extinguishers must be inspected monthly"},
>       {"text": "Emergency evacuation routes must be posted on every floor"},
>       {"text": "Fire drills must be conducted quarterly"}
>     ]
>   }'

Example response 201 Created:

1 {
2   "success": true,
3   "data": {
4     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "name": "Q2 2026 Fire Safety Audit",
6     "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
8     "status": "pending",
9     "total_requirements": 4,
10     "processed_requirements": 0,
11     "passed_requirements": 0,
12     "failed_requirements": 0,
13     "created_at": "2026-05-22T10:00:00Z",
14     "updated_at": "2026-05-22T10:00:00Z"
15   },
16   "request_id": "..."
17 }

POST /api/v2/check/runs/{id}/trigger

Start processing a check run. The system works through each requirement, checking it against project documents.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Request body:

Field	Type	Required	Description
`reprocess`	boolean	No	Re-check requirements that were already completed (default `false`)
`skip_breakdown`	boolean	No	Skip sub-requirement breakdown for faster results (default `false`)

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/trigger \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{}'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "task_id": "task_xyz789",
6     "status": "processing"
7   },
8   "request_id": "..."
9 }

Error responses:

Status	Code	When
`409`	`CONFLICT`	Run is already being processed

GET /api/v2/check/runs

List all compliance check runs. Supports pagination.

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/check/runs/{id}

Get a check run with full results, including all requirements and their verdicts.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "name": "Q2 2026 Fire Safety Audit",
6     "status": "completed",
7     "total_requirements": 4,
8     "processed_requirements": 4,
9     "passed_requirements": 3,
10     "failed_requirements": 1,
11     "processing_started_at": "2026-05-22T10:01:00Z",
12     "processing_completed_at": "2026-05-22T10:04:30Z",
13     "requirements": [
14       {
15         "id": "req-uuid-1",
16         "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
17         "text": "The site must have a documented fire safety plan",
18         "order_index": 0,
19         "status": "completed",
20         "sub_requirements": []
21       }
22     ]
23   },
24   "request_id": "..."
25 }

Run status values:

Status	Meaning
`pending`	Created but not yet triggered
`processing`	Currently checking requirements
`completed`	All requirements checked
`stopped`	Manually stopped before completion
`failed`	Processing failed (system error)

GET /api/v2/check/runs/{id}/requirements

Get the individual requirement-level results from a run. Each requirement includes its verdict, sub-requirements, and evidence.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Example response 200 OK:

1 {
2   "success": true,
3   "data": [
4     {
5       "id": "req-uuid-1",
6       "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7       "text": "The site must have a documented fire safety plan",
8       "order_index": 0,
9       "status": "completed",
10       "sub_requirements": [
11         {
12           "id": "subreq-uuid-1",
13           "requirement_id": "req-uuid-1",
14           "text": "A fire safety plan document must exist",
15           "justification": "The Safety Management Plan (Section 3.1) includes a comprehensive fire safety plan...",
16           "score": 0.94,
17           "status": "comply",
18           "sources": null
19         }
20       ],
21       "created_at": "2026-05-22T10:00:00Z",
22       "updated_at": "2026-05-22T10:03:00Z"
23     }
24   ],
25   "request_id": "..."
26 }

Requirement fields:

Field	Type	Description
`text`	string	The original requirement text
`order_index`	integer	Position in the run (0-based)
`status`	string	`pending`, `processing`, or `completed`
`sub_requirements`	array	Broken-down sub-checks with individual verdicts
`sub_requirements[].justification`	string	Evidence and reasoning for this sub-requirement
`sub_requirements[].score`	number	Confidence score (0 to 1)
`sub_requirements[].status`	string	`comply`, `not-comply`, or `pending`

The Check endpoints verify whether your project documents satisfy specific requirements. Two approaches: quick single-requirement verification, or structured multi-requirement audit runs.

POST /api/v2/check/verify

Verify a single compliance requirement. Synchronous — returns a verdict immediately. Can take up to 5 minutes for complex requirements.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to check against
`requirement`	string	Yes	The requirement to verify (max 5,000 characters)
`handbook_ids`	uuid[]	No	Limit check to specific handbooks. Omit to use all project knowledge

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/verify \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
>     "requirement": "All electrical installations must comply with AS/NZS 3000 wiring standards"
>   }'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "verdict": "COMPLIANT",
5     "confidence": 0.92,
6     "evidence": "Section 4.2 of the Electrical Safety Specification states: 'All wiring installations shall comply with AS/NZS 3000:2018 including amendments.'",
7     "explanation": "The project documentation explicitly references compliance with AS/NZS 3000 in the Electrical Safety Specification. The specification mandates that all subcontractors certify their work against this standard.",
8     "recommendation": null,
9     "sources": [
10       {
11         "handbook_id": "hb-uuid-1",
12         "node_id": "node-uuid-1",
13         "title": "Electrical-Safety-Specification.pdf",
14         "start_page": 8,
15         "end_page": 9
16       }
17     ],
18     "handbook": {
19       "id": "hb-uuid-1",
20       "name": "Electrical Safety Specification"
21     }
22   },
23   "request_id": "..."
24 }

Response fields:

Field	Type	Description
`verdict`	string	`COMPLIANT`, `CONTRADICTS`, or `NOT_FOUND`
`confidence`	number	How certain the AI is (0 to 1). Below 0.7 suggests insufficient evidence
`evidence`	string	Verbatim quote from the source document supporting the verdict
`explanation`	string	Plain-language reasoning for the decision
`recommendation`	string \| null	Suggested action if non-compliant. Null if compliant
`sources`	array	Documents and pages referenced
`sources[].title`	string	Source document name
`sources[].start_page`	integer \| null	Starting page of the relevant section
`sources[].end_page`	integer \| null	Ending page of the relevant section
`handbook`	object	Which handbook was checked against

Verdict values:

Verdict	Meaning
`COMPLIANT`	Requirement is satisfied by project documentation
`CONTRADICTS`	Project documentation contradicts the requirement
`NOT_FOUND`	No evidence for or against — documents may not cover this topic

POST /api/v2/check/runs

Create a compliance check run. Define a set of requirements to check as a batch. Does not start processing — call the trigger endpoint when ready.

Authentication: Bearer token required

Request body:

Field	Type	Required	Description
`project_id`	uuid	Yes	Project to check against
`name`	string	Yes	Run name (e.g., “Q2 2026 Fire Safety Audit”)
`requirements`	array	Yes	Array of requirement objects (1–1,000)
`requirements[].text`	string	Yes	Requirement text (max 5,000 characters)
`requirements[].metadata`	object	No	Optional metadata
`handbook_ids`	uuid[]	No	Limit check to specific handbooks

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/runs \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
>     "name": "Q2 2026 Fire Safety Audit",
>     "requirements": [
>       {"text": "The site must have a documented fire safety plan"},
>       {"text": "Fire extinguishers must be inspected monthly"},
>       {"text": "Emergency evacuation routes must be posted on every floor"},
>       {"text": "Fire drills must be conducted quarterly"}
>     ]
>   }'

Example response 201 Created:

1 {
2   "success": true,
3   "data": {
4     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "name": "Q2 2026 Fire Safety Audit",
6     "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7     "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
8     "status": "pending",
9     "total_requirements": 4,
10     "processed_requirements": 0,
11     "passed_requirements": 0,
12     "failed_requirements": 0,
13     "created_at": "2026-05-22T10:00:00Z",
14     "updated_at": "2026-05-22T10:00:00Z"
15   },
16   "request_id": "..."
17 }

POST /api/v2/check/runs/{id}/trigger

Start processing a check run. The system works through each requirement, checking it against project documents.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Request body:

Field	Type	Required	Description
`reprocess`	boolean	No	Re-check requirements that were already completed (default `false`)
`skip_breakdown`	boolean	No	Skip sub-requirement breakdown for faster results (default `false`)

Example request:

$ curl -X POST https://api.pyramid-ai.com/api/v2/check/runs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/trigger \
>   -H "Authorization: Bearer pai_live_YOUR_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{}'

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "task_id": "task_xyz789",
6     "status": "processing"
7   },
8   "request_id": "..."
9 }

Error responses:

Status	Code	When
`409`	`CONFLICT`	Run is already being processed

GET /api/v2/check/runs

List all compliance check runs. Supports pagination.

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/check/runs/{id}

Get a check run with full results, including all requirements and their verdicts.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Example response 200 OK:

1 {
2   "success": true,
3   "data": {
4     "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5     "name": "Q2 2026 Fire Safety Audit",
6     "status": "completed",
7     "total_requirements": 4,
8     "processed_requirements": 4,
9     "passed_requirements": 3,
10     "failed_requirements": 1,
11     "processing_started_at": "2026-05-22T10:01:00Z",
12     "processing_completed_at": "2026-05-22T10:04:30Z",
13     "requirements": [
14       {
15         "id": "req-uuid-1",
16         "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
17         "text": "The site must have a documented fire safety plan",
18         "order_index": 0,
19         "status": "completed",
20         "sub_requirements": []
21       }
22     ]
23   },
24   "request_id": "..."
25 }

Run status values:

Status	Meaning
`pending`	Created but not yet triggered
`processing`	Currently checking requirements
`completed`	All requirements checked
`stopped`	Manually stopped before completion
`failed`	Processing failed (system error)

GET /api/v2/check/runs/{id}/requirements

Get the individual requirement-level results from a run. Each requirement includes its verdict, sub-requirements, and evidence.

Authentication: Bearer token required

Path parameters:

Parameter	Type	Description
`id`	uuid	Run ID

Example response 200 OK:

1 {
2   "success": true,
3   "data": [
4     {
5       "id": "req-uuid-1",
6       "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7       "text": "The site must have a documented fire safety plan",
8       "order_index": 0,
9       "status": "completed",
10       "sub_requirements": [
11         {
12           "id": "subreq-uuid-1",
13           "requirement_id": "req-uuid-1",
14           "text": "A fire safety plan document must exist",
15           "justification": "The Safety Management Plan (Section 3.1) includes a comprehensive fire safety plan...",
16           "score": 0.94,
17           "status": "comply",
18           "sources": null
19         }
20       ],
21       "created_at": "2026-05-22T10:00:00Z",
22       "updated_at": "2026-05-22T10:03:00Z"
23     }
24   ],
25   "request_id": "..."
26 }

Requirement fields:

Field	Type	Description
`text`	string	The original requirement text
`order_index`	integer	Position in the run (0-based)
`status`	string	`pending`, `processing`, or `completed`
`sub_requirements`	array	Broken-down sub-checks with individual verdicts
`sub_requirements[].justification`	string	Evidence and reasoning for this sub-requirement
`sub_requirements[].score`	number	Confidence score (0 to 1)
`sub_requirements[].status`	string	`comply`, `not-comply`, or `pending`

$	curl -X POST https://api.pyramid-ai.com/api/v2/check/verify \
>	-H "Authorization: Bearer pai_live_YOUR_KEY" \
>	-H "Content-Type: application/json" \
>	-d '{
>	"project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
>	"requirement": "All electrical installations must comply with AS/NZS 3000 wiring standards"
>	}'

1	{
2	"success": true,
3	"data": {
4	"verdict": "COMPLIANT",
5	"confidence": 0.92,
6	"evidence": "Section 4.2 of the Electrical Safety Specification states: 'All wiring installations shall comply with AS/NZS 3000:2018 including amendments.'",
7	"explanation": "The project documentation explicitly references compliance with AS/NZS 3000 in the Electrical Safety Specification. The specification mandates that all subcontractors certify their work against this standard.",
8	"recommendation": null,
9	"sources": [
10	{
11	"handbook_id": "hb-uuid-1",
12	"node_id": "node-uuid-1",
13	"title": "Electrical-Safety-Specification.pdf",
14	"start_page": 8,
15	"end_page": 9
16	}
17	],
18	"handbook": {
19	"id": "hb-uuid-1",
20	"name": "Electrical Safety Specification"
21	}
22	},
23	"request_id": "..."
24	}

1	{
2	"success": true,
3	"data": {
4	"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5	"name": "Q2 2026 Fire Safety Audit",
6	"org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
7	"project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
8	"status": "pending",
9	"total_requirements": 4,
10	"processed_requirements": 0,
11	"passed_requirements": 0,
12	"failed_requirements": 0,
13	"created_at": "2026-05-22T10:00:00Z",
14	"updated_at": "2026-05-22T10:00:00Z"
15	},
16	"request_id": "..."
17	}

1	{
2	"success": true,
3	"data": {
4	"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
5	"task_id": "task_xyz789",
6	"status": "processing"
7	},
8	"request_id": "..."
9	}

1	{
2	"success": true,
3	"data": [
4	{
5	"id": "req-uuid-1",
6	"run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
7	"text": "The site must have a documented fire safety plan",
8	"order_index": 0,
9	"status": "completed",
10	"sub_requirements": [
11	{
12	"id": "subreq-uuid-1",
13	"requirement_id": "req-uuid-1",
14	"text": "A fire safety plan document must exist",
15	"justification": "The Safety Management Plan (Section 3.1) includes a comprehensive fire safety plan...",
16	"score": 0.94,
17	"status": "comply",
18	"sources": null
19	}
20	],
21	"created_at": "2026-05-22T10:00:00Z",
22	"updated_at": "2026-05-22T10:03:00Z"
23	}
24	],
25	"request_id": "..."
26	}