Check | Pyramid AI | Developer Docs

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:

{
  "success": true,
  "data": {
    "verdict": "COMPLIANT",
    "confidence": 0.92,
    "evidence": "Section 4.2 of the Electrical Safety Specification states: 'All wiring installations shall comply with AS/NZS 3000:2018 including amendments.'",
    "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.",
    "recommendation": null,
    "sources": [
      {
        "handbook_id": "hb-uuid-1",
        "node_id": "node-uuid-1",
        "title": "Electrical-Safety-Specification.pdf",
        "start_page": 8,
        "end_page": 9
      }
    ],
    "handbook": {
      "id": "hb-uuid-1",
      "name": "Electrical Safety Specification"
    }
  },
  "request_id": "..."
}

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:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Q2 2026 Fire Safety Audit",
    "org_id": "iPwoNDP1ribwqCTkvlEyiA6DtGZdYe0k",
    "project_id": "7f9c8d2a-1b3e-4c5d-8e9f-0a1b2c3d4e5f",
    "status": "pending",
    "total_requirements": 4,
    "processed_requirements": 0,
    "passed_requirements": 0,
    "failed_requirements": 0,
    "created_at": "2026-05-22T10:00:00Z",
    "updated_at": "2026-05-22T10:00:00Z"
  },
  "request_id": "..."
}

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:

{
  "success": true,
  "data": {
    "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "task_id": "task_xyz789",
    "status": "processing"
  },
  "request_id": "..."
}

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:

{
  "success": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Q2 2026 Fire Safety Audit",
    "status": "completed",
    "total_requirements": 4,
    "processed_requirements": 4,
    "passed_requirements": 3,
    "failed_requirements": 1,
    "processing_started_at": "2026-05-22T10:01:00Z",
    "processing_completed_at": "2026-05-22T10:04:30Z",
    "requirements": [
      {
        "id": "req-uuid-1",
        "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "text": "The site must have a documented fire safety plan",
        "order_index": 0,
        "status": "completed",
        "sub_requirements": []
      }
    ]
  },
  "request_id": "..."
}

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:

{
  "success": true,
  "data": [
    {
      "id": "req-uuid-1",
      "run_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "text": "The site must have a documented fire safety plan",
      "order_index": 0,
      "status": "completed",
      "sub_requirements": [
        {
          "id": "subreq-uuid-1",
          "requirement_id": "req-uuid-1",
          "text": "A fire safety plan document must exist",
          "justification": "The Safety Management Plan (Section 3.1) includes a comprehensive fire safety plan...",
          "score": 0.94,
          "status": "comply",
          "sources": null
        }
      ],
      "created_at": "2026-05-22T10:00:00Z",
      "updated_at": "2026-05-22T10:03:00Z"
    }
  ],
  "request_id": "..."
}

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`