> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://documents.pyramid-ai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://documents.pyramid-ai.com/_mcp/server.

# Check

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

```bash
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`:

```json
{
  "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:**

```bash
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`:

```json
{
  "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:**

```bash
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`:

```json
{
  "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`:

```json
{
  "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`:

```json
{
  "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`            |