# API reference

Every operation in the Proofline Review API 1.0.0, generated from the same OpenAPI document the SDKs are built from. All paths are under `/api/v1/organizations/{org_id}` and take a token with the scope shown.

The full document is at [/docs/openapi.json](/docs/openapi.json).

Each example reads the token, the organization and every other required parameter from an environment variable named after it, such as `REVIEW_ID` for `review_id`.

## Reviews

### Export reviews

`GET /api/v1/organizations/{org_id}/exports/{dataset}`

Export review metadata

Returns one page of a version-1 export dataset (`reviews`, `finding_outcomes`, `finding_validations`, `spend` or `findings`) for an RFC3339 window of at most 31 days, as NDJSON by default or CSV. Rows respect the token's repository restriction.

- Scope: `analytics:read`
- SDKs: no method, because the response is not JSON. Call it over HTTP.
- Returns: `200` as `application/x-ndjson` or `text/csv`, one [ExportRow](#schema-exportrow) per row

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `dataset` | path | [Dataset](#schema-dataset) | yes |  |
| `org_id` | path | string (uuid) | yes |  |
| `cursor` | query | string or null | no | Treat this signed continuation as opaque. Retain the same window and grouping. |
| `format` | query | string or null | no | ndjson (default) or csv. Each CSV page repeats its column header. |
| `from` | query | string | yes | Inclusive RFC3339 creation, debit or first-publication time. At most 31 days. |
| `group_by` | query | [FindingOutcomesGroupBy](#schema-findingoutcomesgroupby) or null | no | `finding_outcomes` only; defaults to repository. |
| `to` | query | string | yes | Exclusive RFC3339 creation, debit or first-publication time. |

```typescript
const organizationId = process.env.PROOFLINE_ORGANIZATION_ID!;
const dataset = process.env.DATASET!;
const query = new URLSearchParams({ from: process.env.FROM!, to: process.env.TO! });
const response = await fetch(
  `https://proofline.sh/api/v1/organizations/${organizationId}/exports/${dataset}?${query}`,
  { headers: { Authorization: `Bearer ${process.env.PROOFLINE_TOKEN!}` } },
);
if (!response.ok) {
  throw new Error(`Proofline answered ${response.status}: ${await response.text()}`);
}
console.log(await response.text());
```

```python
import os
import httpx

token = os.environ["PROOFLINE_TOKEN"]
organization_id = os.environ["PROOFLINE_ORGANIZATION_ID"]
dataset = os.environ["DATASET"]
response = httpx.get(
    f"https://proofline.sh/api/v1/organizations/{organization_id}/exports/{dataset}",
    params={"from": os.environ["FROM"], "to": os.environ["TO"]},
    headers={"Authorization": f"Bearer {token}"},
)
response.raise_for_status()
print(response.text)
```

```sh
curl -sS -G "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/exports/$DATASET" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  --data-urlencode "from=$FROM" \
  --data-urlencode "to=$TO"
```

### List repositories

`GET /api/v1/organizations/{org_id}/repository-names`

List repository names

Returns the ID and full name of each connected repository inside the token's repository restriction, including repositories with no review, so a client can resolve `owner/name` to an ID.

- Scope: `reviews:read`
- TypeScript: `client.listRepositories()`
- Python: `client.list_repositories()`
- Returns: `200` [RepositoryNames](#schema-repositorynames)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.listRepositories({
  path: { org_id: process.env.PROOFLINE_ORGANIZATION_ID! },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.list_repositories(UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]))
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repository-names" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### List reviews

`GET /api/v1/organizations/{org_id}/reviews`

List reviews

Lists the latest run of each pull request in the organization, with filters and cursor pagination. A `search` equal to a full head commit SHA returns the latest run at that commit instead.

- Scope: `reviews:read`
- TypeScript: `client.listReviews()`
- Python: `client.list_reviews()`
- Returns: `200` [ReviewPage](#schema-reviewpage)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `attention` | query | string or null | no | `needed` lists terminal reviews of open pull requests with active findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit. |
| `author` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `environment` | query | string (uuid) or null | no |  |
| `findings` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `limit` | query | integer (int64) or null | no |  |
| `repository` | query | string (uuid) or null | no |  |
| `search` | query | string or null | no |  |
| `status` | query | string or null | no |  |
| `org_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.listReviews({
  path: { org_id: process.env.PROOFLINE_ORGANIZATION_ID! },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.list_reviews(UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]))
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Get review

`GET /api/v1/organizations/{org_id}/reviews/{review_id}`

Get a review

Returns a review with its subjects, assessments and open items. An incomplete assessment reports its gaps; an empty finding list from it says nothing about the change.

- Scope: `reviews:read`
- TypeScript: `client.getReview()`
- Python: `client.get_review()`
- Returns: `200` [CustomerReviewDetail](#schema-customerreviewdetail)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `review_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getReview({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    review_id: process.env.REVIEW_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REVIEW_ID"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/$REVIEW_ID" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Get assessment

`GET /api/v1/organizations/{org_id}/reviews/{review_id}/assessments/{assessment_id}`

Get an assessment

Returns one assessment of a review with its decision, checks and findings.

- Scope: `findings:read`
- TypeScript: `client.getAssessment()`
- Python: `client.get_assessment()`
- Returns: `200` [CustomerAssessmentDetail](#schema-customerassessmentdetail)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `assessment_id` | path | string (uuid) | yes |  |
| `org_id` | path | string (uuid) | yes |  |
| `review_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getAssessment({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    review_id: process.env.REVIEW_ID!,
    assessment_id: process.env.ASSESSMENT_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_assessment(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REVIEW_ID"]),
        UUID(os.environ["ASSESSMENT_ID"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/$REVIEW_ID/assessments/$ASSESSMENT_ID" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Rerun review

`POST /api/v1/organizations/{org_id}/reviews/{review_id}/rerun`

Rerun a review

Creates a new run of the review's original immutable code subject and leaves earlier runs unchanged. A local patch review is not rerun. Requires live GitHub write access; a repeated request can create another run, so clients make one attempt.

- Scope: `reviews:rerun`
- TypeScript: `client.rerunReview()`
- Python: `client.rerun_review()`
- Returns: `200` [RerunResponse](#schema-rerunresponse)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `review_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.rerunReview({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    review_id: process.env.REVIEW_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.rerun_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REVIEW_ID"]),
    )
    print(result)
```

```sh
curl -sS -X POST "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/$REVIEW_ID/rerun" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Get review routing

`GET /api/v1/organizations/{org_id}/reviews/{review_id}/routing`

Get review routing

Returns the review's validated routing plan and recorded finding placements. It reports retained routing facts, not model output or a deployment recommendation.

- Scope: `reviews:read`
- TypeScript: `client.getReviewRouting()`
- Python: `client.get_review_routing()`
- Returns: `200` [ReviewRoutingView](#schema-reviewroutingview)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `review_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getReviewRouting({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    review_id: process.env.REVIEW_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_review_routing(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REVIEW_ID"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/$REVIEW_ID/routing" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Get deployment review

`GET /api/v1/organizations/{org_id}/reviews/deployments/{public_key}`

Get a deployment review

Returns the deployment review with the given public key.

- Scope: `reviews:read`
- TypeScript: `client.getDeploymentReview()`
- Python: `client.get_deployment_review()`
- Returns: `200` [CustomerReviewDetail](#schema-customerreviewdetail)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `public_key` | path | string | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getDeploymentReview({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    public_key: process.env.PUBLIC_KEY!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_deployment_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        os.environ["PUBLIC_KEY"],
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/deployments/$PUBLIC_KEY" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### List pull request reviews

`GET /api/v1/organizations/{org_id}/reviews/pr/{repository}/{pull_request_number}`

List a pull request's review runs

Lists the review runs of one pull request, addressed by repository name and pull request number.

- Scope: `reviews:read`
- TypeScript: `client.listPullRequestReviews()`
- Python: `client.list_pull_request_reviews()`
- Returns: `200` [ReviewPage](#schema-reviewpage)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `pull_request_number` | path | integer (int64) | yes |  |
| `repository` | path | string | yes |  |
| `attention` | query | string or null | no | `needed` lists terminal reviews of open pull requests with active findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit. |
| `author` | query | string or null | no |  |
| `cursor` | query | string or null | no |  |
| `environment` | query | string (uuid) or null | no |  |
| `findings` | query | string or null | no |  |
| `kind` | query | string or null | no |  |
| `limit` | query | integer (int64) or null | no |  |
| `repository` | query | string (uuid) or null | no |  |
| `search` | query | string or null | no |  |
| `status` | query | string or null | no |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.listPullRequestReviews({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    repository: process.env.REPOSITORY!,
    pull_request_number: Number(process.env.PULL_REQUEST_NUMBER),
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.list_pull_request_reviews(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        os.environ["REPOSITORY"],
        int(os.environ["PULL_REQUEST_NUMBER"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/pr/$REPOSITORY/$PULL_REQUEST_NUMBER" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

### Get pull request review

`GET /api/v1/organizations/{org_id}/reviews/pr/{repository}/{pull_request_number}/runs/{run_number}`

Get a pull request review run

Returns one review run of a pull request, addressed by repository name, pull request number and run number.

- Scope: `reviews:read`
- TypeScript: `client.getPullRequestReview()`
- Python: `client.get_pull_request_review()`
- Returns: `200` [CustomerReviewDetail](#schema-customerreviewdetail)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `pull_request_number` | path | integer (int64) | yes |  |
| `repository` | path | string | yes |  |
| `run_number` | path | integer (int64) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getPullRequestReview({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    repository: process.env.REPOSITORY!,
    pull_request_number: Number(process.env.PULL_REQUEST_NUMBER),
    run_number: Number(process.env.RUN_NUMBER),
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_pull_request_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        os.environ["REPOSITORY"],
        int(os.environ["PULL_REQUEST_NUMBER"]),
        int(os.environ["RUN_NUMBER"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/reviews/pr/$REPOSITORY/$PULL_REQUEST_NUMBER/runs/$RUN_NUMBER" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

## Findings

### Get finding

`GET /api/v1/organizations/{org_id}/findings/{finding_id}`

Get a finding

Returns one finding with its evidence references, validation state and causal graph.

- Scope: `findings:read`
- TypeScript: `client.getFinding()`
- Python: `client.get_finding()`
- Returns: `200` [CustomerFinding](#schema-customerfinding)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `finding_id` | path | string (uuid) | yes |  |
| `org_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getFinding({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    finding_id: process.env.FINDING_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_finding(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["FINDING_ID"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/findings/$FINDING_ID" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

## Repositories

### Request patch review

`POST /api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews`

Review local changes

Reviews a unified diff against a commit GitHub has in the repository, and returns that patch's review when one exists. The review reads only that commit and the patch, and is never posted to a pull request. Requires live GitHub read access; the same patch on the same base always returns the same review.

- Scope: `reviews:request`
- TypeScript: `client.requestPatchReview()`
- Python: `client.request_patch_review()`
- Returns: `200` [PatchReviewResponse](#schema-patchreviewresponse)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `repo_id` | path | string (uuid) | yes |  |

Request body: [PatchReviewRequest](#schema-patchreviewrequest)

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.requestPatchReview(
  {
    path: {
      org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
      repo_id: process.env.REPO_ID!,
    },
  },
  { base_commit_sha: process.env.BASE_COMMIT_SHA!, patch: process.env.PATCH! },
);
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import PatchReviewRequest, ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.request_patch_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REPO_ID"]),
        body=PatchReviewRequest(base_commit_sha=os.environ["BASE_COMMIT_SHA"], patch=os.environ["PATCH"]),
    )
    print(result)
```

```sh
curl -sS -X POST "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repositories/$REPO_ID/patch-reviews" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --arg base_commit_sha "$BASE_COMMIT_SHA" --arg patch "$PATCH" '{"base_commit_sha": $base_commit_sha, "patch": $patch}')"
```

### Request review

`POST /api/v1/organizations/{org_id}/repositories/{repo_id}/pull-requests/{number}/review`

Request a pull request review

Returns the active or result-bearing review at the pull request's live head, or creates a withheld one. The `FULL` mode creates a new review of the whole change unless one is pending or running. Requires live GitHub write access; a repeated request can create another review, so clients make one attempt.

- Scope: `reviews:request`
- TypeScript: `client.requestReview()`
- Python: `client.request_review()`
- Returns: `200` [RunNowResponse](#schema-runnowresponse)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `number` | path | integer (int64) | yes |  |
| `org_id` | path | string (uuid) | yes |  |
| `repo_id` | path | string (uuid) | yes |  |

Request body: [RunNowRequest](#schema-runnowrequest)

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.requestReview(
  {
    path: {
      org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
      repo_id: process.env.REPO_ID!,
      number: Number(process.env.NUMBER),
    },
  },
  { mode: "EXISTING_OR_NEW" },
);
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient, RunNowMode, RunNowRequest

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.request_review(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REPO_ID"]),
        int(os.environ["NUMBER"]),
        body=RunNowRequest(mode=RunNowMode.EXISTING_OR_NEW),
    )
    print(result)
```

```sh
curl -sS -X POST "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repositories/$REPO_ID/pull-requests/$NUMBER/review" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode":"EXISTING_OR_NEW"}'
```

### Get review guidance

`GET /api/v1/organizations/{org_id}/repositories/{repo_id}/review-guidance`

Get repository review guidance

Returns the review guidance configured for a repository, for tools and coding agents that read it before writing code.

- Scope: `guidance:read`
- TypeScript: `client.getReviewGuidance()`
- Python: `client.get_review_guidance()`
- Returns: `200` [RepositoryGuidance](#schema-repositoryguidance)

| Parameter | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `org_id` | path | string (uuid) | yes |  |
| `repo_id` | path | string (uuid) | yes |  |

```typescript
import { ProoflineClient } from "@proofline/sdk";

const client = new ProoflineClient({
  baseUrl: "https://proofline.sh",
  token: process.env.PROOFLINE_TOKEN!,
});
const result = await client.getReviewGuidance({
  path: {
    org_id: process.env.PROOFLINE_ORGANIZATION_ID!,
    repo_id: process.env.REPO_ID!,
  },
});
console.log(result);
```

```python
import os
from uuid import UUID
from proofline import ProoflineClient

with ProoflineClient(os.environ["PROOFLINE_TOKEN"]) as client:
    result = client.get_review_guidance(
        UUID(os.environ["PROOFLINE_ORGANIZATION_ID"]),
        UUID(os.environ["REPO_ID"]),
    )
    print(result)
```

```sh
curl -sS "https://proofline.sh/api/v1/organizations/$PROOFLINE_ORGANIZATION_ID/repositories/$REPO_ID/review-guidance" \
  -H "Authorization: Bearer $PROOFLINE_TOKEN"
```

## Schemas

Errors use [Problem](#schema-problem), an RFC 9457 problem document. The HTTP status is authoritative.

### ActionUnavailability

Type: `READ_ONLY`, `REPOSITORY_UNAVAILABLE`, `REPOSITORY_WRITE_REQUIRED`, `PERMISSION_CHECK_UNAVAILABLE`

### ActorView

The person behind an action on a review, as the page names them.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `github_user_id` | integer (int64) | yes | Stable GitHub identity. The login below is display metadata. |
| `login` | string | yes | The login they were known by when they acted. Display metadata. |
| `profile_url` | string or null | no | Their profile on the deployment's GitHub host. |

### AssessmentProjection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessment_id` | string (uuid) | yes | Assessment that owns this route binding. |
| `environment_id` | string (uuid) | yes | Environment that the assessment covers. |
| `pass_output_recorded` | boolean | yes | Whether this assessment retained a generalist output record. |
| `pass_output_sha256` | string or null | no | Digest of the immutable generalist output, when the assessment retained one. |
| `passes` | array of [PassProjection](#schema-passprojection) | yes | Pass and symbolic model binding retained by the plan. |
| `reach` | string | yes | Environment reach retained by the plan. |

### AttributedChange

How one condition relates to the review's base revision.

Type: string or string or string or string or string

### AttributedConditionView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `change` | [AttributedChange](#schema-attributedchange) | yes | How this condition relates to the review's base revision. |
| `reviewed_tree_citations` | array of [ReviewedTreeCitationView](#schema-reviewedtreecitationview) | yes | The member that declares the site at each revision that declares it. |
| `revision` | [AttributedRevision](#schema-attributedrevision) | yes | The revision that holds the condition: the base for `RESOLVED`, the proposed revision for `INTRODUCED`, `CHANGED` and `UNCHANGED`, and either for `UNATTRIBUTED`. |
| `subject` | [UntrustedText](#schema-untrustedtext) | yes | World's label of the condition's site and what it declares, such as `.github/workflows/ci.yml jobs.test.steps[0].uses: actions/checkout@v4`. It quotes repository text. |

### AttributedRevision

Type: string or string

### AttributionStatus

Type: string or string or string

### AuthorChoice

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | integer (int64) | yes | The pull request author's GitHub user ID, the value the `author` filter accepts. |
| `login` | string or null | no | The author's most recently recorded GitHub login, a display label. Null when none is recorded. |

### Authority

Type: `ADVISORY`, `DEPLOYMENT_POLICY`

### Availability

Type: `RECORDED`, `NOT_RECORDED`, `LEGACY`, `OPERATIONAL_FAILURE` or string

### ChangeAttributionView

Which conditions behind a check's result the change brought, and which World found at the review's base revision. It sits beside the result and never changes it: a condition already at the base is still a condition.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `complete_record` | [CompleteRecordView](#schema-completerecordview) or null | no | Where every condition is recorded when some are omitted. Absent when `conditions` lists them all. |
| `condition_count` | integer (uint32) | yes | How many conditions World attributed, listed or not. Zero unless `status` is `COMPARED`. |
| `conditions` | array of [AttributedConditionView](#schema-attributedconditionview) | yes | Every condition, each once, in World's order, never netted against another. Empty unless `status` is `COMPARED`, and empty when some are omitted: it never lists only some of them. |
| `counts` | array of [ChangeCountView](#schema-changecountview) | yes | How many conditions there are of each change at each revision, over every condition, listed or not. Changes with none are left out. |
| `detail_code` | string or null | no | World's code for why it could not read that revision, such as `BASE_REVIEWED_TREE_NOT_DECLARED`. Present exactly when `status` is `UNAVAILABLE`. |
| `listed_conditions` | array of [AttributedConditionView](#schema-attributedconditionview) or null | no | The conditions a summary lists when some are omitted: the first ones in the order `counts` gives, each whole, at most 50 and always fewer than `condition_count`. Present exactly when `omitted_condition_count` is not zero. |
| `omitted_condition_count` | integer (uint32) | yes | How many of those conditions this response does not list. Zero when the result kept World's attribution whole. Otherwise the result kept a summary: `listed_conditions` lists the first ones, `counts` is still exact, and World's recorded evaluation holds every condition. |
| `revision` | [AttributedRevision](#schema-attributedrevision) or null | no | The revision World could not read. Present exactly when `status` is `UNAVAILABLE`. |
| `status` | [AttributionStatus](#schema-attributionstatus) | yes | Whether World compared both revisions, could not read one, or recorded an attribution this build cannot read. |

### ChangeCountView

How many conditions are of one change at one revision.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `change` | [AttributedChange](#schema-attributedchange) | yes | How the counted conditions relate to the review's base revision. |
| `count` | integer (uint32) | yes | How many conditions have this `change` at this `revision`, over every condition, listed or not. |
| `revision` | [AttributedRevision](#schema-attributedrevision) | yes | The revision that holds the counted conditions. |

### CheckLifecycle

World's lifecycle disclosure for the evaluator version that answered, as the receipt recorded it. A deployment gate counts only `GATING` results (`DeterministicCoverage::gate_effective_status`), and only when it evaluates a deployment; the lifecycle alone permits or blocks nothing.

Type: string or string or string or string or string

### CommentAddressEvaluationView

One stored post-merge judgment of a finding comment.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `evaluated_at` | string (date-time) | yes | When the evaluation was made. |
| `outcome` | [CommentAddressOutcome](#schema-commentaddressoutcome) | yes | `ADDRESSED`, `NOT_ADDRESSED`, or `INCOMPLETE` when the merged code could not be judged. |
| `reason` | string | yes | Server-authored reason. Render as text. |

### CommentAddressOutcome

Type: `ADDRESSED`, `NOT_ADDRESSED`, `INCOMPLETE`

### CommentReaction

Type: `THUMBS_UP`, `THUMBS_DOWN`, `LAUGH`, `HOORAY`, `CONFUSED`, `HEART`, `ROCKET`, `EYES`

### CommentReactionView

One stored reaction on the finding's root comment.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor_github_user_id` | integer (int64) | yes | The stable GitHub identity of whoever reacted. |
| `actor_login` | string or null | no | Provider text. Render as text. |
| `github_comment_id` | integer (int64) | yes | The GitHub comment the reaction is on: the finding's root comment. |
| `reaction` | [CommentReaction](#schema-commentreaction) | yes | The reaction as GitHub names it. |

### CompleteRecordView

World's immutable record of the complete answer an omitted list comes from.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `attribution_digest` | string | yes | The `sha256:` digest of the complete attribution in that record. |
| `world_evaluation_id` | string | yes | The evaluation World recorded, which holds every condition. |

### CustomerAssessment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checks` | [CustomerChecks](#schema-customerchecks) | yes | The deterministic World checks recorded for this assessment. |
| `completed_at` | string (date-time) or null | no | When the assessment completed. Null while it has not. |
| `decision_presentation` | [CustomerDecision](#schema-customerdecision) or null | no | The retained decision disclosure, which grants no deployment authorization. Absent when none is recorded and the review kind records no decision basis. |
| `domains` | array of [DomainView](#schema-domainview) | yes | The risk domains the assessment evaluated, each with its status and reason, ordered by domain. |
| `environment_display_name` | string | yes | The display name of the environment this assessment covers. |
| `findings` | array of [CustomerFinding](#schema-customerfinding) | yes | The findings this assessment recorded, `SERIOUS` first. |
| `id` | string (uuid) | yes | The assessment's ID. |
| `incompleteness_kind` | string or null | no | Why an `INCOMPLETE` assessment is incomplete: `NOT_CONFIGURED`, `POLICY_EXCLUDED`, `EVIDENCE_UNAVAILABLE`, `HYPOTHESES_UNRESOLVED` or `MODEL_BUDGET_EXHAUSTED`. Absent otherwise; an unclassified gap is not a complete assessment. |
| `reason_codes` | array of string or null | no | The assessment gap codes the backend recorded. Absent on historical records. |
| `release_evidence_gap` | string or null | no | The typed gap the automatic release-set read recorded. Null when the read is pending, pinned a release, or was never attempted. |
| `started_at` | string (date-time) or null | no | When the assessment started. Null until it starts. |
| `status` | string | yes | The assessment's recorded status, such as `RUNNING`, `COMPLETED` or `INCOMPLETE`. |

### CustomerAssessmentDetail

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `checks` | [CustomerChecks](#schema-customerchecks) | yes | The deterministic World checks recorded for this assessment. |
| `completed_at` | string (date-time) or null | no | When the assessment completed. Null while it has not. |
| `decision_presentation` | [CustomerDecision](#schema-customerdecision) or null | no | The retained decision disclosure, which grants no deployment authorization. Absent when none is recorded and the review kind records no decision basis. |
| `domains` | array of [DomainView](#schema-domainview) | yes | The risk domains the assessment evaluated, each with its status and reason, ordered by domain. |
| `environment_display_name` | string | yes | The display name of the environment this assessment covers. |
| `findings` | array of [CustomerFinding](#schema-customerfinding) | yes | The findings this assessment recorded, `SERIOUS` first. |
| `id` | string (uuid) | yes | The assessment's ID. |
| `incompleteness_kind` | string or null | no | Why an `INCOMPLETE` assessment is incomplete: `NOT_CONFIGURED`, `POLICY_EXCLUDED`, `EVIDENCE_UNAVAILABLE`, `HYPOTHESES_UNRESOLVED` or `MODEL_BUDGET_EXHAUSTED`. Absent otherwise; an unclassified gap is not a complete assessment. |
| `reason_codes` | array of string or null | no | The assessment gap codes the backend recorded. Absent on historical records. |
| `release_evidence_gap` | string or null | no | The typed gap the automatic release-set read recorded. Null when the read is pending, pinned a release, or was never attempted. |
| `review_id` | string (uuid) | yes | The review this assessment belongs to. |
| `started_at` | string (date-time) or null | no | When the assessment started. Null until it starts. |
| `status` | string | yes | The assessment's recorded status, such as `RUNNING`, `COMPLETED` or `INCOMPLETE`. |
| `subjects` | array of [SubjectView](#schema-subjectview) | yes | The review subjects this assessment's own release set authorized, plus each `PRIMARY` subject that carries no release authorization. |

### CustomerCheck

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `change_attribution` | [ChangeAttributionView](#schema-changeattributionview) or null | no | Which conditions behind the outcome the change brought and which were already at the review's base revision. It never changes the outcome: a condition already at the base is pre-existing, not safe. Absent for a check whose evaluator does not compare the two revisions. |
| `detail` | string or null | no | Why World refused the check, or otherwise World's recorded explanation of the result. Null when neither is recorded. |
| `evaluated_at` | string or null | no | When World evaluated this answer. A reused answer is evidence from this instant, which can precede the assessment. |
| `lifecycle` | [CheckLifecycle](#schema-checklifecycle) | yes | The lifecycle of the evaluator version that answered. It says whether a deployment gate could count this result, not whether one did. |
| `name` | string | yes | The check's readable name, derived from its key. |
| `outcome` | string | yes | The outcome the receipt recorded, which is the outcome a deployment gate weighed: `READY`, `BLOCKED`, `UNRESOLVED`, `UNAVAILABLE`, `NOT_APPLICABLE` or `NOT_ASKED`. A verdict never rewrites it. |
| `unresolved_reason` | [UnresolvedReason](#schema-unresolvedreason) or null | no | Why an `UNRESOLVED` check did not settle, as World's verdict gave it. Absent on every other outcome, and on an unresolved receipt whose verdict names none of these reasons. |

### CustomerChecks

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `families` | array of [CustomerCheck](#schema-customercheck) | yes | One entry per recorded check result, ordered by check key and version. Empty when no receipt exists. |
| `receipt_recorded` | boolean | yes | Whether these checks come from an immutable deterministic coverage receipt. When false, no check result is recorded. |
| `status` | string | yes | The receipt's status, or `PENDING`, `SUPERSEDED`, `STOPPED`, `NOT_ATTEMPTED` or `UNAVAILABLE` when no receipt exists. |

### CustomerDecision

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authority` | [Authority](#schema-authority) | yes | Whether the decision is `ADVISORY` or comes from a `DEPLOYMENT_POLICY`. |
| `availability` | [Availability](#schema-availability) | yes | Whether a verified decision record is present, absent, legacy, failed, or too large for this projection. |
| `basis` | [CustomerDecisionBasis](#schema-customerdecisionbasis) or null | no | The permission, evidence classification and reason code of the verified recorded basis. Null when no verified basis is recorded. |
| `gate_state` | [GateState](#schema-gatestate) or null | no | The local deployment gate state and any recorded override. Null unless the decision belongs to a deployment gate. |

### CustomerDecisionBasis

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `evidence` | [EvidenceView](#schema-evidenceview) | yes | How the recorded basis classified its evidence. |
| `permission` | [PermissionView](#schema-permissionview) | yes | The permission the recorded basis reached: `PERMIT` or `BLOCK`. |
| `reason_code` | string | yes | The reason code the recorded basis gives for its permission. |

### CustomerEvidenceRef

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `commit_sha` | string or null | no | The commit a file or commit reference reads. Null for other kinds, and for a file reference whose review recorded no head commit. |
| `companion_repository` | string or null | no | The repository a `companion_repository_file` reference reads from. Null for every other kind. |
| `end_line` | integer (uint32) or null | no | The last cited line of a file reference. Null when the reference names no end line or is not a file reference. |
| `kind` | string | yes | The reference's kind: `repository_file`, `companion_repository_file`, `commit`, `workflow_run`, `world_entity`, `deterministic_test`, `recorded_read` or `text`. |
| `label` | string | yes | The reference's display label, such as a path with its line range. A recorded read or an unnamed World entity carries a fixed label, and a deterministic test carries its check's readable name. |
| `legacy_text` | string or null | no | The unstructured text of a `text` reference. Null for structured references and for recorded reads. |
| `provenance_status` | string | yes | How the reference was obtained: `VERIFIED_REPOSITORY_READ`, `PINNED_WORLD_ENTITY`, `EXECUTED_DETERMINISTIC_TEST`, `PROVIDER_REFERENCE`, `RECORDED_READ` or `LEGACY_UNSTRUCTURED`. |
| `repository_path` | string or null | no | The cited file's path for a file reference. Null for every other kind. |
| `start_line` | integer (uint32) or null | no | The first cited line of a file reference. Null when the reference cites no line or is not a file reference. |
| `url` | string or null | no | The link the reference resolves to. Null when it resolves to none or the review's repository or head commit is unknown. |
| `workflow_attempt` | integer (int32) or null | no | The run attempt of a `workflow_run` reference. Null when the reference names no attempt or is another kind. |
| `workflow_run_id` | integer (int64) or null | no | The GitHub Actions run ID of a `workflow_run` reference. Null for every other kind. |

### CustomerFinding

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `causal_graph` | [FindingCausalGraphView](#schema-findingcausalgraphview) or null | no | The typed causal graph the reviewer supplied for an ordering or reachability finding. Null when the finding carries none. |
| `claim` | string | yes | What the reviewer states is wrong. |
| `comment_evaluation` | [CommentAddressEvaluationView](#schema-commentaddressevaluationview) or null | no | The post-merge judgment of whether the finding comment was addressed. It is not a finding decision; null when none is recorded. |
| `comment_reactions` | array of [CommentReactionView](#schema-commentreactionview) | yes | Emoji reactions stored on the Proofline finding comment. They are not a finding decision. |
| `evidence_class` | [FindingEvidenceClass](#schema-findingevidenceclass) or null | no | The kind of proof the finding rests on, derived from the typed evidence it cites. Null on findings recorded before the class existed. |
| `evidence_refs` | array of [CustomerEvidenceRef](#schema-customerevidenceref) | yes | The references the finding cites, resolved as the pull request comment resolves them. |
| `github_comment_url` | string or null | no | The inline GitHub comment published for this occurrence of the finding. Null when none was published; earlier runs are never used as a fallback. |
| `id` | string (uuid) | yes | The finding's ID. |
| `impact` | string | yes | The consequence the reviewer states the claim has. |
| `latest_validation` | [CustomerFindingValidation](#schema-customerfindingvalidation) or null | no | The latest decision on the finding's series, with who made it, where and when. Null when no decision is recorded. |
| `lifecycle_state` | string | yes | The finding's recorded lifecycle state: `NEW`, `UNCHANGED`, `RESOLVED` or `REINTRODUCED`. |
| `remediation` | string or null | no | The reviewer's proposed fix. Null when it proposed none. |
| `risk_domain` | string | yes | The risk domain the reviewer assigned to the finding. |
| `severity` | string | yes | `SERIOUS` or `WARNING`. |
| `supporting_evidence` | [FindingSupport](#schema-findingsupport) or null | no | The verdict explanation and evidence of the supported hypothesis that produced this finding. Null when the finding links no supported hypothesis. |
| `symbols` | array of string | yes | The code identifiers the reviewer declared in the finding's prose, in declaration order, so a reader can set each as code. |
| `thread_observation` | [ThreadObservationView](#schema-threadobservationview) or null | no | The latest observation of the finding's GitHub thread state. It is not a finding decision; null when none is recorded. |
| `validation` | string or null | no | The latest decision on the finding, the same value `latest_validation` carries. Null when no decision is recorded. |

### CustomerFindingValidation

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor_github_user_id` | integer (int64) or null | no | The actor's stable GitHub user ID. Null for the automatic decision. |
| `actor_login` | string or null | no | The actor's GitHub login, a display label to render as text. Null for the automatic decision. |
| `covering_author_kind` | string or null | no | For `ALREADY_COVERED`, `HUMAN` or `BOT`. Null for every other decision. |
| `covering_author_login` | string or null | no | For `ALREADY_COVERED`, the login of whoever wrote the covering comment, to render as text. Null for every other decision. |
| `covering_comment_created_at` | string (date-time) or null | no | For `ALREADY_COVERED`, when the covering comment was written. Null for every other decision. |
| `github_comment_url` | string or null | no | The comment that carried a decision made on GitHub, or, for `ALREADY_COVERED`, the other reviewer's comment the decision rests on. |
| `recorded_at` | string (date-time) | yes | When Proofline recorded the decision. |
| `source` | string | yes | Where the decision came from: `UI` for the app's assessment controls, `GITHUB_COMMENT` for a pull request comment, or `PROOFLINE` for the automatic `ALREADY_COVERED` decision. |
| `validation` | string | yes | The decision: `CONFIRMED`, `DISMISSED`, `FIXED`, `ACCEPTED_RISK` or `ALREADY_COVERED`. |

### CustomerReviewDetail

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actions` | [ReviewActions](#schema-reviewactions) | yes | Which review actions the caller may take now. |
| `assessment_count` | integer (int64) | yes | How many environment assessments this review has. |
| `assessments` | array of [CustomerAssessment](#schema-customerassessment) | yes | The environment assessments this review recorded. |
| `base_branch_commit_sha` | string or null | no | The base branch tip GitHub reported when the review was triggered, display metadata that differs from `base_commit_sha` when the base branch moved after the branch point. |
| `base_commit_sha` | string or null | no | The base revision the review compares against; for a pull request, the merge base of its head and base branch. Null until pinned, and for a first deployment. |
| `base_commit_url` | string or null | no | The GitHub page for `base_commit_sha`. Null when that commit or the repository is unknown. |
| `base_ref` | string or null | no | The pull request's base branch name as last recorded from GitHub, for orientation only. Null when no pull request state is recorded. |
| `check_run_url` | string or null | no | The GitHub check run Proofline published for this review. Null when none was published. |
| `compare_url` | string or null | no | The GitHub comparison of the base and head commits. Null unless both are pinned and the repository is known, and for a patch review, whose head GitHub does not have. |
| `completed_at` | string (date-time) or null | no | When the review reached a terminal status. Absent while it is still pending or running. |
| `created_at` | string (date-time) | yes | When the review was created. |
| `current_head_commit_sha` | string or null | no | The pull request's head commit as the latest provider projection reports it, which can differ from `head_commit_sha`. Set only on a single-review read, and absent for a deployment review or a pull request with no projection. |
| `diff_stats` | [ReviewDiffStats](#schema-reviewdiffstats) or null | no | Line totals from this run's pinned comparison. Null until recorded, or when the provider's changed-file list was incomplete. |
| `environment_display_names` | array of string | yes | Display names of this review's assessed environments, not current repository links. |
| `finding_count` | integer (int64) | yes | How many findings this review's assessments recorded, across all of them. |
| `head_commit_sha` | string or null | no | The head commit this review is pinned to. For a patch review, the revision ID Proofline derives from its base commit and patch digest, which is not a commit. Absent when the review recorded none. |
| `head_commit_url` | string or null | no | The exact revision reviewed. A commit URL, never a branch URL: the branch moves, the reviewed input does not. Absent for a patch review. |
| `head_ref` | string or null | no | The pull request's head branch name as last recorded from GitHub, for orientation only. Null when no pull request state is recorded. |
| `id` | string (uuid) | yes | The review's identifier. |
| `kind` | string | yes | `PULL_REQUEST`, `DEPLOYMENT` or `PATCH`, a review of local changes sent as a patch. |
| `merge_gate` | [PullRequestMergeGate](#schema-pullrequestmergegate) or null | no | The deterministic policy for this exact repository/head, when opted in. Its captured review owner and GitHub bypass remain separate history. |
| `open_items` | [OpenItemsView](#schema-openitemsview) or null | no | What Proofline still has open for the reviewed head, counted from the current finding decisions. Absent while the review is `PENDING` or `RUNNING`. |
| `open_items_observation` | [ReviewOpenItems](#schema-reviewopenitems) or null | no | Dated PR counts with head, evaluated-scope and bounded thread proof. Absent when that observation is unavailable; scalar counts remain separate. |
| `public_key` | string | yes | The review's stable public address: `rev_` followed by its identifier without hyphens. |
| `publication` | string | yes | Whether the review reached the pull request: `PUBLISHED`, `WITHHELD`, `PUBLICATION_REQUESTED` or `PUBLICATION_REFUSED`. A review run from Proofline is withheld until somebody publishes it. |
| `publication_detail` | string or null | no | Why a publication was refused, or how one failed. Server text. |
| `pull_request_author_avatar_url` | string or null | no | Provider-supplied avatar URL. Login-derived `.png` URLs do not work for GitHub App bot accounts and are not portable across GitHub hosts. |
| `pull_request_author_github_user_id` | integer (int64) or null | no | The author's stable GitHub user id: identity for profile lookups, never display text. Absent when GitHub named no author. |
| `pull_request_author_login` | string or null | no | Provider display metadata for the pull request author, not the rerun requester. |
| `pull_request_author_url` | string or null | no | The author's profile on the deployment's GitHub host. Absent when no author login is known. |
| `pull_request_number` | integer (int64) or null | no | The pull request number. Absent for a deployment or patch review. |
| `pull_request_state` | string or null | no | Current provider state of the pull request: `OPEN`, `CLOSED`, or `MERGED`. Absent for deployment reviews or a missing projection. |
| `pull_request_title` | string or null | no | The pull request's title as provider state last reported it, so it names the change rather than only numbering it. Untrusted text: renderers must treat it as text, never markup. |
| `pull_request_url` | string or null | no | The pull request on GitHub. Absent for a deployment review or when the repository is unknown. |
| `related_reviews` | array of [RelatedReview](#schema-relatedreview) | yes | Every other run for this pull request the caller can see, plus reviews joined to this one by supersession or rerun. |
| `repository_full_name` | string or null | no | The repository's `owner/name`. Absent when the review names no repository. |
| `repository_id` | string (uuid) or null | no | The review's repository. Set only on a single-review read, and absent there when the review names no repository. |
| `repository_name` | string or null | no | The repository's name within its owner. Absent when the review names no repository. |
| `repository_url` | string or null | no | The repository on GitHub. Absent when the deployment's web base cannot be joined with the stored name. |
| `requested_by` | [ActorView](#schema-actorview) or null | no | Who asked for this review, for a review a person requested. Null on automatic reviews and on reviews recorded before requesters were. |
| `review_comment_url` | string or null | no | The pull request review Proofline submitted for this review. Null when it submitted none. |
| `review_retracted_at` | string (date-time) or null | no | When a submitted pull request review was marked retracted, a marker only older versions set. Null otherwise. |
| `run_number` | integer (int64) or null | no | One-based, append-only ordinal within one repository pull request. |
| `status` | string | yes | The review's lifecycle status: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED` or `EXCLUDED`. |
| `stoppable` | boolean | yes | Whether the stop action applies: the review is `PENDING` or `RUNNING` and decides no deployment gate. It says nothing about the caller's permission. |
| `stopped_at` | string (date-time) or null | no | When the review was stopped. Null unless it was stopped. |
| `stopped_by` | [ActorView](#schema-actorview) or null | no | Who stopped this review, for a `STOPPED` review whose stop recorded its actor. Null otherwise. |
| `stopped_from` | string or null | no | Where the review was stopped: `PROOFLINE` or `PULL_REQUEST`. Null unless the stop recorded it. |
| `subjects` | array of [SubjectView](#schema-subjectview) | yes | What this review covers: the revision under review and any companion repositories, workflow runs, artifacts or deployments. |
| `superseded_by_review_id` | string (uuid) or null | no | The newer review that superseded this one. Null when none did or the caller cannot see it. |
| `trigger_origin` | string | yes | Who asked for this review: `AUTOMATIC`, `COMMAND`, `RERUN`, `MANUAL`, or `UNKNOWN` for a trigger key this build does not recognise. |

### Dataset

Type: `reviews`, `finding_outcomes`, `finding_validations`, `spend`, `findings`

### DomainView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `domain` | string | yes | The risk domain this evaluation covers. |
| `reason` | string | yes | Why the domain was considered or skipped, as recorded with the evaluation. |
| `status` | string | yes | `CONSIDERED` or `SKIPPED`. |

### EvidenceView

Type: `REQUIRED_PROPERTIES_ESTABLISHED`, `INCOMPLETE`, `NO_APPLICABLE_OBLIGATIONS`

### ExportEvidenceKind

Type: `repository_file`, `repository_file_at_commit`, `companion_repository_file`, `commit`, `workflow_run`, `world_entity`, `deterministic_test`, `recorded_read`, `text`

### ExportEvidenceRef

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | Stable opaque occurrence-local identity, independent of evidence values. |
| `kind` | [ExportEvidenceKind](#schema-exportevidencekind) | yes | The recorded reference kind, or `text` for a kind this export does not recognize. |

### ExportFindingLifecycle

Type: `NEW`, `UNCHANGED`, `RESOLVED`, `REINTRODUCED`

### ExportFindingSeverity

Type: `WARNING`, `SERIOUS`

### ExportReviewKind

Type: `PULL_REQUEST`, `DEPLOYMENT`, `PATCH`

### ExportReviewStatus

Type: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED`, `EXCLUDED`

### ExportRow

The closed row vocabulary of the existing raw-stream export operation.

Type: [ReviewsExportRow](#schema-reviewsexportrow) or [FindingOutcomesExportRow](#schema-findingoutcomesexportrow) or [FindingValidationsExportRow](#schema-findingvalidationsexportrow) or [SpendExportRow](#schema-spendexportrow) or [FindingsExportRow](#schema-findingsexportrow)

### ExportValidation

Type: `UNKNOWN`, `CONFIRMED`, `DISMISSED`, `FIXED`, `ACCEPTED_RISK`, `ALREADY_COVERED`

### ExportValidationSource

Type: `ui`, `github_comment`, `proofline`

### FileProjection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `depth` | string | yes | The code-inspection depth retained by the plan. |
| `passes` | array of string | yes | The review passes bound to this file. |
| `path` | string | yes | Repository-relative path retained by the routing plan. |

### FilterChoice

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string (uuid) | yes | The repository or environment ID to pass as the filter value. |
| `name` | string | yes | The repository's full name or the environment's display name. |

### FindingCausalEdgeView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `from` | string | yes | The `id` of the node the edge starts at. |
| `label` | string or null | no | What the relation is. Model-authored text, and absent when the reviewer gave none. |
| `to` | string | yes | The `id` of the node the edge ends at. |

### FindingCausalGraphView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `edges` | array of [FindingCausalEdgeView](#schema-findingcausaledgeview) | yes | Directed relations between nodes. An edge can name a node identifier that no node carries. |
| `nodes` | array of [FindingCausalNodeView](#schema-findingcausalnodeview) | yes | The actors in the finding, as the reviewer named them. |

### FindingCausalNodeView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | yes | The reviewer-assigned node identifier that edges refer to. Model-authored text. |
| `label` | string | yes | What the node is. Model-authored text: render as text. |
| `role` | string | yes | One of `change`, `dependency`, `failure`, `blocked` or `ok`, or empty; a value outside that set is returned as recorded. |

### FindingEvidenceClass

Type: `ANALYZER_BACKED`, `CODE_ONLY` or string or string

### FindingOutcomesCount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int64) | yes | Published finding series in the group whose series disposition is `RESOLVED_BY_PUSH`. |
| `drilldown` | [FindingOutcomesDrilldown](#schema-findingoutcomesdrilldown) | yes | The query that lists the series behind `count`. |

### FindingOutcomesDrilldown

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `group_key` | string | yes | The `group_key` query value that limits the listed series to this count's group. |
| `outcome` | [FindingOutcomesOutcome](#schema-findingoutcomesoutcome) or null | no | The `outcome` query value for an `outcome` selector, and null for every other selector. |
| `post_merge` | [FindingOutcomesPostMergeOutcome](#schema-findingoutcomespostmergeoutcome) or null | no | The `post_merge` query value for a `post_merge` selector, and null for every other selector. |
| `selector` | [FindingOutcomesSelector](#schema-findingoutcomesselector) | yes | The `selector` query value that lists the series behind this count. |

### FindingOutcomesExportRow

Exact shared aggregate counts for one admitted group and requested window.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `code_changed` | [FindingOutcomesCount](#schema-findingoutcomescount) | yes | Published series whose series disposition is `RESOLVED_BY_PUSH`. |
| `dataset_version` | integer (uint16) | yes | The row contract version, always `1`. |
| `external_validation_denominator` | integer (int64) | yes | Human-validated series; excludes automatic coverage and unrecorded outcomes. |
| `from` | string (date-time) | yes | The inclusive start of the requested first-publication window. |
| `group_by` | [FindingOutcomesGroupBy](#schema-findingoutcomesgroupby) | yes | The dimension that defines this row's group. |
| `key` | string | yes | The grouping value: a repository or environment ID, a risk domain, a severity or a review kind, as `group_by` selects. |
| `limitations` | array of string | yes | Gaps in publication history that keep findings outside these counts; they mean missing history, not zero findings. |
| `name` | string | yes | The group's display name: the repository's full name (or `Repository` and its ID when no name is recorded), the environment's display name, or otherwise `key`. |
| `organization_id` | string (uuid) | yes | The organization whose findings are counted. |
| `outcomes` | array of [FindingOutcomesOutcomeCount](#schema-findingoutcomesoutcomecount) | yes | One count per outcome, always all six `FindingOutcomesOutcome` values in a fixed order. |
| `post_merge` | [FindingOutcomesPostMergeCounts](#schema-findingoutcomespostmergecounts) | yes | Published series counted by their latest post-merge comment-address evaluation. |
| `published` | integer (int64) | yes | Finding series in the group whose first publication falls inside the window. |
| `to` | string (date-time) | yes | The exclusive end of the requested first-publication window. |

### FindingOutcomesGroupBy

Type: `repository`, `environment`, `risk_domain`, `severity`, `subject_kind`

### FindingOutcomesOutcome

Type: `FIXED`, `CONFIRMED`, `ACCEPTED_RISK`, `DISMISSED`, `ALREADY_COVERED`, `NO_RECORDED_OUTCOME`

### FindingOutcomesOutcomeCount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int64) | yes | Published finding series in the group whose latest qualifying outcome is `outcome`. |
| `drilldown` | [FindingOutcomesDrilldown](#schema-findingoutcomesdrilldown) | yes | The query that lists the series behind `count`. |
| `outcome` | [FindingOutcomesOutcome](#schema-findingoutcomesoutcome) | yes | The outcome counted, where `NO_RECORDED_OUTCOME` means the series has no qualifying validation. |
| `validation_sources` | [FindingOutcomesValidationSources](#schema-findingoutcomesvalidationsources) | yes | `count` split by where the outcome was recorded; a `NO_RECORDED_OUTCOME` count has no source. |

### FindingOutcomesPostMergeCount

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `count` | integer (int64) | yes | Published finding series in the group whose latest evaluation recorded `outcome`. |
| `drilldown` | [FindingOutcomesDrilldown](#schema-findingoutcomesdrilldown) | yes | The query that lists the series behind `count`. |
| `outcome` | [FindingOutcomesPostMergeOutcome](#schema-findingoutcomespostmergeoutcome) | yes | The outcome of the series' latest comment-address evaluation. |

### FindingOutcomesPostMergeCounts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `judged` | integer (int64) | yes | Series with a retained evaluation, rather than all published series. |
| `outcomes` | array of [FindingOutcomesPostMergeCount](#schema-findingoutcomespostmergecount) | yes | One count per post-merge outcome, always `ADDRESSED`, `NOT_ADDRESSED` and `INCOMPLETE` in that order. |

### FindingOutcomesPostMergeOutcome

Type: `ADDRESSED`, `NOT_ADDRESSED`, `INCOMPLETE`

### FindingOutcomesSelector

Type: `outcome`, `code_changed`, `post_merge`

### FindingOutcomesValidationSources

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `console` | integer (int64) | yes | Series whose outcome comes from a validation recorded in the console. |
| `github_reply` | integer (int64) | yes | Series whose outcome comes from a validation recorded by a GitHub comment reply. |
| `proofline` | integer (int64) | yes | Series whose outcome is `ALREADY_COVERED`, recorded by Proofline itself. |

### FindingSupport

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `evidence_refs` | array of [CustomerEvidenceRef](#schema-customerevidenceref) | yes | The references the hypothesis cites for its verdict. |
| `explanation` | [UntrustedText](#schema-untrustedtext) or null | no | Why the hypothesis reached its verdict, as recorded at resolution. Null when no explanation is recorded. |

### FindingValidationsExportRow

One append-only validation, including its recorded actor display metadata. Missing historical actors stay absent; the export does not infer identity.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `actor_github_user_id` | integer (int64) or null | no | The GitHub user ID captured as the actor, null when none was captured. |
| `actor_login` | string or null | no | The GitHub login captured as display metadata at validation time, null when none was captured. |
| `actor_user_id` | string (uuid) or null | no | The Proofline user captured as the actor, null when none was captured. |
| `created_at` | string (date-time) | yes | When the validation was recorded; the export window filters on this time. |
| `dataset_version` | integer (uint16) | yes | The row contract version, always `1`. |
| `environment_id` | string (uuid) | yes | The environment of the assessment that recorded the finding. |
| `expires_at` | string (date-time) or null | no | When the decision expires, null when it records no expiry. |
| `finding_id` | string (uuid) | yes | The finding occurrence the validation applies to. |
| `organization_id` | string (uuid) | yes | The organization that owns the finding. |
| `repository_id` | string (uuid) or null | no | The review's primary repository, null when the review records none. |
| `review_id` | string (uuid) | yes | The review whose assessment recorded the finding. |
| `source` | [ExportValidationSource](#schema-exportvalidationsource) | yes | Where the decision was recorded: `ui` or `github_comment` for a person, `proofline` for automatic coverage. |
| `validation` | [ExportValidation](#schema-exportvalidation) | yes | The recorded decision, including legacy `UNKNOWN` values. |
| `validation_id` | string (uuid) | yes | The stable ID of this validation record. |

### FindingsExportRow

One immutable finding occurrence. Reference payloads and evidence values stay private.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessment_id` | string (uuid) | yes | The environment assessment that recorded the finding. |
| `claim` | string | yes | The finding's claim, with supported credential shapes masked as `<REDACTED:kind>`. |
| `created_at` | string (date-time) | yes | When the finding was recorded; the export window filters on this time. |
| `dataset_version` | integer (uint16) | yes | The row contract version, always `1`. |
| `environment_id` | string (uuid) | yes | The environment the assessment covers. |
| `evidence_refs` | array of [ExportEvidenceRef](#schema-exportevidenceref) | yes | The finding's evidence references in recorded order, each reduced to a kind and an opaque ID; an empty list means the finding records none. |
| `finding_id` | string (uuid) | yes | The stable ID of this finding occurrence. |
| `impact` | string | yes | The finding's stated impact, with supported credential shapes masked. |
| `lifecycle_state` | [ExportFindingLifecycle](#schema-exportfindinglifecycle) | yes | The occurrence's recorded lifecycle state relative to earlier occurrences. |
| `organization_id` | string (uuid) | yes | The organization that owns the finding. |
| `remediation` | string or null | no | The suggested remediation with credential shapes masked, null when none is recorded. |
| `repository_id` | string (uuid) or null | no | The review's primary repository, null when the review records none. |
| `review_id` | string (uuid) | yes | The review whose assessment recorded the finding. |
| `risk_domain` | string | yes | The risk domain the finding is recorded under. |
| `series_id` | string (uuid) or null | no | The finding series this occurrence belongs to, null when it belongs to none. |
| `severity` | [ExportFindingSeverity](#schema-exportfindingseverity) | yes | The finding's recorded severity. |

### GateState

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `override_record` | [Override](#schema-override) or null | no | Recorded override authorization, not confirmation of provider delivery. |
| `status` | string | yes | Local gate state. ALLOWED/BLOCKED can precede provider delivery. This field does not confirm that GitHub released or blocked a run. |

### GateStatus

Type: `REQUESTED`, `EVALUATING`, `ALLOWED`, `BLOCKED`, `BYPASSED`, `SUPERSEDED`

### NotAssessedView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `environment_display_name` | string | yes | The display name of the environment whose assessment is not `COMPLETED`. |
| `incompleteness_kind` | string or null | no | The assessment's recorded gap class. Absent is an unclassified gap, never a complete assessment. |

### OpenFindingCounts

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `serious` | integer (uint64) | yes | Finding series with `SERIOUS` severity that are unresolved and not under an unexpired dismissal or risk acceptance. |
| `warning` | integer (uint64) | yes | Finding series with `WARNING` severity that are unresolved and not under an unexpired dismissal or risk acceptance. |

### OpenItemEnvironment

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display_name` | string | yes | The environment's display name. |
| `environment_id` | string (uuid) | yes | The environment whose assessment is not complete. |
| `reason` | [OpenItemsGapReason](#schema-openitemsgapreason) | yes | Why the assessment is not complete, derived from its status and recorded gap class; `UNKNOWN` when neither names a cause. |
| `status` | [OpenItemsReviewStatus](#schema-openitemsreviewstatus) | yes | The assessment's recorded status. |

### OpenItemsGapReason

Type: `NOT_STARTED`, `IN_PROGRESS`, `NOT_CONFIGURED`, `POLICY_EXCLUDED`, `EVIDENCE_UNAVAILABLE`, `HYPOTHESES_UNRESOLVED`, `MODEL_BUDGET_EXHAUSTED`, `FAILED`, `STOPPED`, `UNKNOWN`

### OpenItemsHeadState

Type: `CURRENT`, `OUTDATED`, `UNKNOWN`

### OpenItemsReviewStatus

Type: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED`, `EXCLUDED`, `UNKNOWN`

### OpenItemsThreadUnknown

Type: `GITHUB_UNAVAILABLE`, `READ_LIMIT_EXCEEDED`, `TRUNCATED`, `RECORDED_THREAD_MISSING`, `REPOSITORY_UNAVAILABLE`

### OpenItemsThreads

Type: object or object

### OpenItemsView

Recorded unresolved findings, accepted risks and assessment gaps. Coverage and notification suppression do not resolve a finding. These scalar counts make no claim about current heads, evaluated scope or threads.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted_risks` | integer (uint) | yes | Finding series whose current decision is an unexpired `ACCEPTED_RISK`. |
| `not_assessed` | array of [NotAssessedView](#schema-notassessedview) | yes | Recorded assessment gaps, including explicit policy exclusions. |
| `open_findings` | integer (uint) | yes | Unresolved recorded finding series, including notification-suppressed findings, decisions whose dismissal or risk acceptance expired, and earlier published series of the pull request that this review did not find again. |
| `serious_findings` | integer (uint) | yes | The `SERIOUS` findings among `open_findings`. |

### Outcome

Type: `ALLOW`, `BLOCK`

### Override

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `comment` | string or null | no | The comment recorded with the approval, truncated past 8000 characters. |
| `github_environment_id` | integer (int64) | yes | The GitHub environment ID the approval applied to. |
| `github_user_id` | integer (int64) | yes | The GitHub user ID of the person whose GitHub deployment approval overrode the gate. |
| `github_user_login` | string | yes | That person's GitHub login as recorded with the approval, a display label truncated past 128 characters. |

### PassProjection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `model_binding` | string | yes | Symbolic configuration binding, not a historical model identity. |
| `name` | string | yes | Pass name from the closed routing schema. |

### PatchReviewRequest

Local changes to review: a unified diff against a commit GitHub has.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `base_commit_sha` | string | yes | The full 40-character commit the patch applies to. GitHub must have it in this repository. |
| `patch` | string | yes | The changes as `git diff --no-ext-diff --no-color <base>` prints them, at most 5 MiB and 3000 files. Text changes only: binary changes, symbolic links and submodules are refused. |

### PatchReviewResponse

What a patch review request produced.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `existing` | boolean | yes | True when this patch on this base already had a review and that one is returned. Sending the same patch twice reviews it once. |
| `patch_digest` | string | yes | SHA-256 of the canonical patch, the identity the review pins with the repository and base commit. |
| `review_id` | string (uuid) | yes | The review of this patch on this base, readable through the review and findings routes. |

### PermissionView

Type: `PERMIT`, `BLOCK`

### PlanProjection

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessments` | array of [AssessmentProjection](#schema-assessmentprojection) | yes | Environment assessment bindings recorded in the plan. |
| `base_sha` | string | yes | Base commit pinned by the change digest. |
| `change_digest_sha256` | string | yes | Digest of the exact retained change input. |
| `fallback_causes` | array of string | yes | Safe codes for fallback causes. Unrecognized values are never echoed. |
| `files` | array of [FileProjection](#schema-fileprojection) | yes | File routing facts recorded in the plan. |
| `head_sha` | string | yes | Head commit pinned by the change digest. |
| `repository_id` | string (uuid) | yes | Repository named by the validated immutable plan. |

### Problem

RFC 9457 problem-details body. `type` is omitted and therefore `about:blank`: the `title`/`detail` pair carries the meaning.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string or null | no | A caller-safe explanation of this occurrence, absent when the cause is an internal error that is logged rather than returned. |
| `status` | integer (uint16) | yes | The HTTP status code of the response that carries this body. |
| `title` | string | yes | A short, stable summary of the problem class, such as `not found` or `conflict`. |

### PullRequestMergeGate

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessment_count` | integer (int32) or null | no | The number of environment assessments counted by the recorded decision. Null before a decision. |
| `blocking_severity` | string | yes | The frozen blocking threshold, either SERIOUS or WARNING; later settings do not restamp it. |
| `bypassed_at` | string (date-time) or null | no | When the bypass receipt was recorded. Null when this gate has no recorded bypass. |
| `coverage_digest` | string or null | no | The digest of the deterministic coverage used by the decision, or null when no digest was recorded. |
| `decided_at` | string (date-time) or null | no | When the immutable decision was recorded. Null before a decision. |
| `decision` | [Outcome](#schema-outcome) or null | no | The immutable ALLOW or BLOCK decision. Null until a decision is recorded. |
| `finding_count` | integer (int32) or null | no | The number of blocking findings counted by the recorded decision. Null before a decision. |
| `head_sha` | string | yes | The exact lowercase commit SHA whose captured policy this gate evaluates. |
| `id` | string (uuid) | yes | The immutable identity of the gate captured for this tenant, repository and head. |
| `merge_commit_sha` | string or null | no | The exact merge commit reported by GitHub for the bypass, or null when none was reported. |
| `merged_by_github_user_id` | integer (int64) or null | no | The stable GitHub user ID reported by a merged-close bypass, or null when none was reported. |
| `merged_pull_request_number` | integer (int64) or null | no | The actual pull request merged in the recorded bypass, which may differ from the captured PR. |
| `policy_version` | string | yes | The deterministic policy version frozen when this gate was captured. |
| `pull_request_number` | integer (int64) | yes | The first pull request that captured this head's gate; a shared-head merge may name another PR. |
| `reason_code` | string or null | no | The recorded deterministic decision or refusal reason. Null until a decision is recorded. |
| `review_id` | string (uuid) or null | no | The first review captured for this gate. Null when its trigger was refused before a review existed. |
| `status` | [GateStatus](#schema-gatestatus) | yes | The current gate projection, including a recorded bypass or supersession by a newer head. |

### RefusedEnvironment

An environment a refusal names. `external_key` is how its pages are addressed.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `display_name` | string | yes | The environment's display name. Tenant free text: render as text. |
| `external_key` | string | yes | The environment's stable machine key, unique within the organization. |
| `id` | string (uuid) | yes | The environment's identifier. |
| `status` | string | yes | The environment's lifecycle status, such as `READY`. |

### RelatedReview

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `created_at` | string (date-time) | yes | When the related review was created. |
| `head_commit_sha` | string or null | no | The head commit the related review is pinned to. Absent when it recorded none. |
| `public_key` | string | yes | The related review's stable public address. |
| `relation` | string | yes | A direct lineage relation, or `EARLIER_RUN` / `LATER_RUN` when the two reviews share a pull request without a direct lineage edge. |
| `review_id` | string (uuid) | yes | The related review's identifier. |
| `run_number` | integer (int64) or null | no | The related review's one-based ordinal within its pull request. Absent for a review that is not of a pull request. |
| `status` | string | yes | The related review's lifecycle status. |

### RepositoryGuidance

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additional_prompt` | string or null | no | The repository-specific reviewer guidance new reviews snapshot, null when none is set. |
| `repository_id` | string (uuid) | yes | The repository's stable Proofline ID. |

### RepositoryName

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `full_name` | string | yes | The provider's `owner/name`. Display metadata: it can change on a rename, so callers keep `id`. |
| `id` | string (uuid) | yes | The repository's stable Proofline ID. |

### RepositoryNames

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `repositories` | array of [RepositoryName](#schema-repositoryname) | yes | The organization's repositories that are not deleted, ordered by name; a repository-restricted token sees only its allowlist. |

### RerunResponse

Manual rerun: a new review of the same immutable subjects, under a fresh trigger key so history accumulates instead of overwriting.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `public_key` | string | yes | The new review's stable public address. |
| `pull_request_number` | integer (int64) or null | no | The pull request number. Absent for a deployment review. |
| `repository_name` | string or null | no | The repository's name within its owner. Absent when the original review names no repository. |
| `review_id` | string (uuid) | yes | The new review's identifier. |
| `run_number` | integer (int64) or null | no | The new review's one-based ordinal within its pull request. Absent for a deployment review. |

### ReviewActions

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `publish` | boolean | yes | Whether the caller may publish this pull request review's withheld results, which requires a browser session and repository write access. |
| `rerun` | boolean | yes | Whether the caller may rerun this review. |
| `stop` | boolean | yes | Whether the caller may stop this review from a browser session. |
| `unavailable_reason` | [ActionUnavailability](#schema-actionunavailability) or null | no | Why an action is unavailable, when a permission or repository check denied it. Null when no check denied one, which does not mean every action is allowed. |
| `validate_findings` | boolean | yes | Whether the caller may record decisions on findings from a browser session. |

### ReviewDiffStats

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `additions` | integer (int64) | yes | Lines added across every changed file in the pinned comparison. |
| `deletions` | integer (int64) | yes | Lines deleted across every changed file in the pinned comparison. |

### ReviewFilters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `authors` | array of [AuthorChoice](#schema-authorchoice) | yes | Authors of visible pull request reviews, one per GitHub user. |
| `environments` | array of [FilterChoice](#schema-filterchoice) | yes | Environments assessed by at least one visible review, ordered by display name. |
| `repositories` | array of [FilterChoice](#schema-filterchoice) | yes | Repositories that have at least one visible review, ordered by full name. |

### ReviewOpenItems

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted_risk_count` | integer (uint64) | yes | Finding series whose current decision is an unexpired `ACCEPTED_RISK`. |
| `current_head_provider_updated_at` | string (date-time) or null | no | GitHub's update time for the recorded pull request state that `current_head_sha` comes from. Null when none is recorded. |
| `current_head_sha` | string or null | no | The pull request's head commit as Proofline last recorded it from GitHub. Null when no pull request state is recorded. |
| `environments` | array of [OpenItemEnvironment](#schema-openitemenvironment) | yes | This review's environment assessments that are not `COMPLETED`, ordered by environment key. |
| `evaluated_scope_known` | boolean | yes | Whether the review recorded at least one environment assessment. False means the evaluated scope is unknown, so an empty `environments` proves nothing. |
| `head_state` | [OpenItemsHeadState](#schema-openitemsheadstate) | yes | Whether `reviewed_head_sha` matches `current_head_sha`; `UNKNOWN` when either is missing. |
| `is_latest_review` | boolean | yes | Whether this review is the newest review of its pull request the caller can see. |
| `latest_review_head_sha` | string or null | no | The head commit of the newest review of this pull request the caller can see. Null when that review recorded none. |
| `latest_review_head_state` | [OpenItemsHeadState](#schema-openitemsheadstate) | yes | Whether `latest_review_head_sha` matches `current_head_sha`; `UNKNOWN` when either is missing. |
| `observed_at` | string (date-time) | yes | When the database facts in this observation were read, all from one statement. |
| `open_findings` | [OpenFindingCounts](#schema-openfindingcounts) | yes | Unresolved finding series that still demand attention, by severity: this review's own, and earlier published series of the pull request that this review did not find again. |
| `review_status` | [OpenItemsReviewStatus](#schema-openitemsreviewstatus) | yes | This review's recorded status; `UNKNOWN` for a status this build does not recognize. |
| `reviewed_head_sha` | string or null | no | The head commit this review evaluated. Null when the review recorded none. |
| `threads` | [OpenItemsThreads](#schema-openitemsthreads) | yes | The count of unresolved Proofline review threads on GitHub, or why that count is unknown. |

### ReviewPage

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `filters` | [ReviewFilters](#schema-reviewfilters) | yes | The values the review list can be filtered by, drawn from reviews the caller can see and independent of the current filters. |
| `items` | array of [ReviewSummary](#schema-reviewsummary) | yes | The reviews on this page, newest first. |
| `next_cursor` | string or null | no | The cursor that requests the next page. Null when `truncated` is false. |
| `truncated` | boolean | yes | Whether more reviews match the query beyond this page. |

### ReviewRoutingView

Type: object or object or object

### ReviewSummary

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessment_count` | integer (int64) | yes | How many environment assessments this review has. |
| `completed_at` | string (date-time) or null | no | When the review reached a terminal status. Absent while it is still pending or running. |
| `created_at` | string (date-time) | yes | When the review was created. |
| `current_head_commit_sha` | string or null | no | The pull request's head commit as the latest provider projection reports it, which can differ from `head_commit_sha`. Set only on a single-review read, and absent for a deployment review or a pull request with no projection. |
| `environment_display_names` | array of string | yes | Display names of this review's assessed environments, not current repository links. |
| `finding_count` | integer (int64) | yes | How many findings this review's assessments recorded, across all of them. |
| `head_commit_sha` | string or null | no | The head commit this review is pinned to. For a patch review, the revision ID Proofline derives from its base commit and patch digest, which is not a commit. Absent when the review recorded none. |
| `head_commit_url` | string or null | no | The exact revision reviewed. A commit URL, never a branch URL: the branch moves, the reviewed input does not. Absent for a patch review. |
| `id` | string (uuid) | yes | The review's identifier. |
| `kind` | string | yes | `PULL_REQUEST`, `DEPLOYMENT` or `PATCH`, a review of local changes sent as a patch. |
| `public_key` | string | yes | The review's stable public address: `rev_` followed by its identifier without hyphens. |
| `publication` | string | yes | Whether the review reached the pull request: `PUBLISHED`, `WITHHELD`, `PUBLICATION_REQUESTED` or `PUBLICATION_REFUSED`. A review run from Proofline is withheld until somebody publishes it. |
| `publication_detail` | string or null | no | Why a publication was refused, or how one failed. Server text. |
| `pull_request_author_avatar_url` | string or null | no | Provider-supplied avatar URL. Login-derived `.png` URLs do not work for GitHub App bot accounts and are not portable across GitHub hosts. |
| `pull_request_author_github_user_id` | integer (int64) or null | no | The author's stable GitHub user id: identity for profile lookups, never display text. Absent when GitHub named no author. |
| `pull_request_author_login` | string or null | no | Provider display metadata for the pull request author, not the rerun requester. |
| `pull_request_author_url` | string or null | no | The author's profile on the deployment's GitHub host. Absent when no author login is known. |
| `pull_request_number` | integer (int64) or null | no | The pull request number. Absent for a deployment or patch review. |
| `pull_request_state` | string or null | no | Current provider state of the pull request: `OPEN`, `CLOSED`, or `MERGED`. Absent for deployment reviews or a missing projection. |
| `pull_request_title` | string or null | no | The pull request's title as provider state last reported it, so it names the change rather than only numbering it. Untrusted text: renderers must treat it as text, never markup. |
| `pull_request_url` | string or null | no | The pull request on GitHub. Absent for a deployment review or when the repository is unknown. |
| `repository_full_name` | string or null | no | The repository's `owner/name`. Absent when the review names no repository. |
| `repository_id` | string (uuid) or null | no | The review's repository. Set only on a single-review read, and absent there when the review names no repository. |
| `repository_name` | string or null | no | The repository's name within its owner. Absent when the review names no repository. |
| `repository_url` | string or null | no | The repository on GitHub. Absent when the deployment's web base cannot be joined with the stored name. |
| `run_number` | integer (int64) or null | no | One-based, append-only ordinal within one repository pull request. |
| `status` | string | yes | The review's lifecycle status: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED` or `EXCLUDED`. |
| `trigger_origin` | string | yes | Who asked for this review: `AUTOMATIC`, `COMMAND`, `RERUN`, `MANUAL`, or `UNKNOWN` for a trigger key this build does not recognise. |

### ReviewedTreeCitationView

One member of a review's declared tree that World cited.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `content_sha256` | string or null | no | The member's content hash. Absent for a member a `REJECTED` population refused, because such a population keeps no members. |
| `overlay_digest` | string | yes | The overlay World read the member from. |
| `path` | [UntrustedText](#schema-untrustedtext) | yes | The member's path in the repository at that revision. Repository text, so it can hold bidirectional controls that reorder what the reader sees. |
| `population_kind` | string | yes | The population the member belongs to, such as `WORKFLOW_DEFINITIONS`. |
| `role` | string | yes | `PROPOSED_CODE_REVISION` (the reviewed commit) or `BASE_CODE_REVISION` (its merge base). |

### ReviewsExportRow

The NDJSON row and CSV column contract. Repository names are display data; the stable repository ID and recorded commit identify the reviewed input.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `base_commit_sha` | string or null | no | The pinned base commit SHA, null when the review records none. |
| `completed_at` | string (date-time) or null | no | When the review finished, null while it has not. |
| `created_at` | string (date-time) | yes | When the review was created; the export window filters on this time. |
| `dataset_version` | integer (uint16) | yes | The row contract version, always `1`. |
| `github_repository_id` | integer (int64) or null | no | GitHub's ID for the repository, null when the organization no longer owns it or the review records no repository. |
| `head_commit_sha` | string or null | no | The pinned head commit SHA, null when the review records none. |
| `kind` | [ExportReviewKind](#schema-exportreviewkind) | yes | Whether the review analyzes a pull request, a deployment or a local patch. |
| `organization_id` | string (uuid) | yes | The organization that owns the review. |
| `pull_request_number` | integer (int64) or null | no | The pull request number, null when the review records none, as for a deployment. |
| `repository_full_name` | string or null | no | The repository's current `owner/name` display name, null when the organization no longer owns it or the review records no repository. |
| `repository_id` | string (uuid) or null | no | The stable ID of the review's primary repository, null when the review records none. |
| `review_id` | string (uuid) | yes | The review's stable ID. |
| `run_number` | integer (int64) or null | no | The review's ordinal among the reviews of its pull request, null for a review without a repository and pull request. |
| `status` | [ExportReviewStatus](#schema-exportreviewstatus) | yes | The review's recorded status. |
| `trigger_origin` | string | yes | What started the review, derived from its trigger key: `AUTOMATIC`, `COMMAND`, `RERUN`, `MANUAL`, or `UNKNOWN` for a key this build does not recognize. |

### ReviewsMetadataStream

UTF-8 metadata file. NDJSON contains one ExportRow per line; CSV contains that dataset's named columns and a header. This response is neither a JSON object nor a JSON array.

Type: string

### RoutingFindingView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `fallback_cause` | string or null | no | Recognized safe fallback cause, when present. |
| `finding_id` | string (uuid) | yes | Finding whose retained placement is reported. |
| `floor_reason` | string or null | no | Recognized safe floor reason, when present. |
| `placement` | string | yes | Publication channel recorded for this finding. |
| `reason_codes` | array of string | yes | Recognized safe reason codes; unknown values are represented as `UNRECOGNIZED`. |
| `rule` | string | yes | Rule that produced the recorded placement. |

### RunNowMode

Whether an explicit request may reuse a settled review of the live head.

Type: `EXISTING_OR_NEW`, `FULL`

### RunNowRefusalView

Why a run-now request created nothing, each reason with what the page needs to link the setting to change.

Type: object or object or object or object or object or object or object or object or object or object

### RunNowRefused

A run-now request that created nothing, as the 400 it is answered with. The refusal is a configuration fact, not a failure, and it is still sent as an RFC 9457 problem: `title`, `status` and `detail` are what a client that knows only problems shows, and `repository_name` and `refusal` are the extension members a client that knows refusals links from. During a rollout a page loaded from the previous bundle keeps working against this server, because a refusal was a 400 with a `detail` before too.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `detail` | string | yes | One sentence naming the condition and the setting to change, for a reader with no link to follow. |
| `refusal` | [RunNowRefusalView](#schema-runnowrefusalview) | yes | Why nothing was created, with what the page needs to link the setting to change. |
| `repository_name` | string | yes | The repository's name within its owner, as its pages are addressed. |
| `status` | integer (uint16) | yes | Always 400. |
| `title` | string | yes | Always `invalid request`. |

### RunNowRequest

An empty body keeps the run-now behavior existing clients request.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `mode` | [RunNowMode](#schema-runnowmode) | no | `EXISTING_OR_NEW`, the default, returns any review that already owns the live head; `FULL` returns only a pending or running review of that head and otherwise starts a new one. |

### RunNowResponse

What a run-now request produced: a review of the live head, created by this request or found already owning the head.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `automatic_reviews_paused` | boolean | yes | True when automatic reviews are stopped on this pull request. The review ran anyway; the flag is why the page can say so. |
| `existing` | boolean | yes | True when this head already carried a review and that one is returned. Clicking twice does not run twice. |
| `review_id` | string (uuid) | yes | The review that owns the live head, new or existing. |
| `run_number` | integer (int64) | yes | The review's one-based ordinal within its pull request, which completes the run's console address. |

### SpendAccountKind

Type: `DEPLOYMENT`, `TENANT_CREDENTIAL`, `UNATTRIBUTED`

### SpendExportRow

UTC daily debit totals using only the account and transport recorded at charge time.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `account` | string or null | no | Recorded attribution, not a current credential label or inferred account. |
| `account_kind` | [SpendAccountKind](#schema-spendaccountkind) | yes | The account kind recorded at charge time, `UNATTRIBUTED` when the debit records none. |
| `dataset_version` | integer (uint16) | yes | The row contract version, always `1`. |
| `day` | string (date-time) | yes | UTC midnight. The requested window can cover only part of this day. |
| `debits` | integer (int64) | yes | The number of debits summed into this row. |
| `microcredits` | integer (int64) | yes | Exact integer charge units; one credit contains one million microcredits. |
| `organization_id` | string (uuid) | yes | The organization charged. |
| `transport` | string or null | no | The model transport recorded at charge time, null when the debit records none. |

### SubjectAuthorization

One assessment's authorization of one subject, by identity. The display name is not the answer on its own: an environment's external key is unique within its organization and a display name is mutable metadata, so two environments of one review can carry the same one. Collapsing to it would leave a reader unable to tell which assessment authorized the subject and which one gapped, which is the confusion this field exists to remove.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `assessment_id` | string (uuid) | yes | The assessment this authorization belongs to, as `AssessmentView.id` names it. A reader joins on this, never on the display name. |
| `environment_display_name` | string | yes | What a reader recognizes the environment by. Display metadata, and tenant free text: a consumer contains it before rendering. |
| `environment_external_key` | string | yes | The environment's stable machine key, unique within the organization. |
| `environment_id` | string (uuid) | yes | The environment the authorizing assessment belongs to. |

### SubjectView

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `artifact_digest` | string or null | no | An immutable OCI digest, never a mutable tag. |
| `commit_sha` | string or null | no | The pinned commit of a `GIT_REVISION` subject, or the base commit a `GIT_PATCH` subject applies to. Absent for other kinds. |
| `deployment_external_id` | string or null | no | The GitHub deployment identifier a `GITHUB_WORKFLOW_RUN` subject ran for. Absent when the run was not for a deployment. |
| `id` | string (uuid) | yes | The subject's stable identifier. It holds across a poll refresh even when a concurrently populated subject shifts this response's `(kind, id)` order: a client keying its own local UI state (an open disclosure, a focused control) by array index would otherwise lose that state to a reorder that changed nothing it owns. |
| `kind` | string | yes | `GIT_REVISION`, `GIT_PATCH`, `GITHUB_WORKFLOW_RUN`, `ARTIFACT` or `DEPLOYMENT`. |
| `patch_digest` | string or null | no | The SHA-256 of a `GIT_PATCH` subject's canonical patch. Absent for other kinds. |
| `release_authorizations` | array of [SubjectAuthorization](#schema-subjectauthorization) | yes | The assessments whose own verified release set authorized this subject. A review with several environments accumulates one subject list, but authorization is per assessment: an artifact one environment's read authenticated is not evidence for a neighbour whose own read gapped or refused. Naming the assessments keeps the union from reading as a shared fact. Empty for a subject no release-set read produced (the reviewed revision, the workflow run, a deployment), because those are the review's own coordinates rather than one environment's authenticated evidence, not because every environment refused them. |
| `repository_full_name` | string or null | no | Absent only when the subject's repository record itself is gone. |
| `repository_id` | string (uuid) or null | no | The immutable repository identity of this subject, including companions. |
| `role` | string | yes | `PRIMARY` for the revision under review; `COMPANION` for context read from another authenticated repository. |
| `url` | string or null | no | The subject on GitHub: the commit for a revision, the run for a workflow run. Absent for kinds GitHub does not address (`GIT_PATCH`, ARTIFACT, DEPLOYMENT) or when the subject's repository is unknown. |
| `workflow_attempt` | integer (int32) or null | no | The attempt number of a `GITHUB_WORKFLOW_RUN` subject. Absent for other kinds. |
| `workflow_run_id` | integer (int64) or null | no | The GitHub Actions run of a `GITHUB_WORKFLOW_RUN` subject. Absent for other kinds. |

### ThreadObservationFreshness

Type: `FRESH`, `STALE`

### ThreadObservationView

A read of GitHub's thread state. `observed_at` is when Proofline read it.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `freshness` | [ThreadObservationFreshness](#schema-threadobservationfreshness) | yes | `STALE` when the pull request is open and this observation is more than 24 hours old, otherwise `FRESH`. |
| `github_comment_url` | string or null | no | The finding's root comment on GitHub. Absent when the repository is unknown. |
| `observed_at` | string (date-time) | yes | When Proofline read the thread state from GitHub. |
| `provider_state` | [ThreadProviderState](#schema-threadproviderstate) or null | no | Absent only when the provider read failed before GitHub returned state. |
| `reply_evidence` | [ThreadReplyEvidence](#schema-threadreplyevidence) | yes | `RECORDED` when a human reply in the thread was recorded, `NONE_CONFIRMED` when the complete thread held none, and `INCOMPLETE` when the thread could not be read in full. |
| `resolver_github_user_id` | integer (int64) or null | no | The stable GitHub identity of whoever resolved the thread. Absent when GitHub named no resolver. |
| `resolver_login` | string or null | no | The login of whoever resolved the thread, as GitHub reported it. Provider text, and absent when GitHub named no resolver. |

### ThreadProviderState

Type: `OPEN`, `RESOLVED`

### ThreadReplyEvidence

Type: `RECORDED`, `NONE_CONFIRMED`, `INCOMPLETE`

### UnresolvedReason

World's reason an executed check did not settle. A gate weighs the three alike, and each asks the reader for a different response.

Type: string or string or string

### UntrustedText

Text that came out of the reviewer model, or out of a repository the model read. It is data, never markup, never a URL, never an instruction. The wrapper exists so the untrustedness cannot be lost on the way to a renderer: there is no field on a turn that carries this text under a name a client could mistake for something safe, and unwrapping it is a deliberate act in the client's own code.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `untrusted_text` | string | yes | The text itself. Render it as plain text only. |