{ "components": { "schemas": { "ActionUnavailability": { "enum": [ "READ_ONLY", "REPOSITORY_UNAVAILABLE", "REPOSITORY_WRITE_REQUIRED", "PERMISSION_CHECK_UNAVAILABLE" ], "type": "string" }, "ActorView": { "description": "The person behind an action on a review, as the page names them.", "properties": { "github_user_id": { "description": "Stable GitHub identity. The login below is display metadata.", "format": "int64", "type": "integer" }, "login": { "description": "The login they were known by when they acted. Display metadata.", "type": "string" }, "profile_url": { "description": "Their profile on the deployment's GitHub host.", "type": [ "string", "null" ] } }, "required": [ "github_user_id", "login" ], "type": "object" }, "AssessmentProjection": { "properties": { "assessment_id": { "description": "Assessment that owns this route binding.", "format": "uuid", "type": "string" }, "environment_id": { "description": "Environment that the assessment covers.", "format": "uuid", "type": "string" }, "pass_output_recorded": { "description": "Whether this assessment retained a generalist output record.", "type": "boolean" }, "pass_output_sha256": { "description": "Digest of the immutable generalist output, when the assessment retained one.", "type": [ "string", "null" ] }, "passes": { "description": "Pass and symbolic model binding retained by the plan.", "items": { "$ref": "#/components/schemas/PassProjection" }, "type": "array" }, "reach": { "description": "Environment reach retained by the plan.", "type": "string" } }, "required": [ "assessment_id", "environment_id", "reach", "passes", "pass_output_recorded" ], "type": "object" }, "AttributedChange": { "description": "How one condition relates to the review's base revision.", "oneOf": [ { "const": "INTRODUCED", "description": "The proposed revision holds the condition and the base did not.", "type": "string" }, { "const": "CHANGED", "description": "The site held a different condition at the base.", "type": "string" }, { "const": "UNCHANGED", "description": "The base already held this condition at this site. Pre-existing,\n not safe.", "type": "string" }, { "const": "RESOLVED", "description": "The base held this condition and the proposed revision no longer does.", "type": "string" }, { "const": "UNATTRIBUTED", "description": "World could not match the condition with its predecessor, such as a\n declaration that may have moved; its origin is unknown.", "type": "string" } ] }, "AttributedConditionView": { "properties": { "change": { "allOf": [ { "$ref": "#/components/schemas/AttributedChange" } ], "description": "How this condition relates to the review's base revision." }, "reviewed_tree_citations": { "description": "The member that declares the site at each revision that declares it.", "items": { "$ref": "#/components/schemas/ReviewedTreeCitationView" }, "type": "array" }, "revision": { "allOf": [ { "$ref": "#/components/schemas/AttributedRevision" } ], "description": "The revision that holds the condition: the base for `RESOLVED`, the\n proposed revision for `INTRODUCED`, `CHANGED` and `UNCHANGED`, and\n either for `UNATTRIBUTED`." }, "subject": { "allOf": [ { "$ref": "#/components/schemas/UntrustedText" } ], "description": "World's label of the condition's site and what it declares, such as\n `.github/workflows/ci.yml jobs.test.steps[0].uses: actions/checkout@v4`.\n It quotes repository text." } }, "required": [ "change", "revision", "subject", "reviewed_tree_citations" ], "type": "object" }, "AttributedRevision": { "oneOf": [ { "const": "PROPOSED_CODE_REVISION", "description": "The reviewed commit.", "type": "string" }, { "const": "BASE_CODE_REVISION", "description": "Its merge base.", "type": "string" } ] }, "AttributionStatus": { "oneOf": [ { "const": "COMPARED", "description": "World read the complete set of conditions at both revisions.", "type": "string" }, { "const": "UNAVAILABLE", "description": "World could not read one revision's conditions, so no condition is\n called new or old.", "type": "string" }, { "const": "UNREADABLE", "description": "The receipt carries an attribution this build cannot read. No\n condition is called new or old.", "type": "string" } ] }, "AuthorChoice": { "properties": { "id": { "description": "The pull request author's GitHub user ID, the value the `author` filter\n accepts.", "format": "int64", "type": "integer" }, "login": { "description": "The author's most recently recorded GitHub login, a display label. Null\n when none is recorded.", "type": [ "string", "null" ] } }, "required": [ "id" ], "type": "object" }, "Authority": { "enum": [ "ADVISORY", "DEPLOYMENT_POLICY" ], "type": "string" }, "Availability": { "oneOf": [ { "enum": [ "RECORDED", "NOT_RECORDED", "LEGACY", "OPERATIONAL_FAILURE" ], "type": "string" }, { "const": "LIMITED", "description": "The record is verified but too large for this projection to carry.\n Siblings still render; nothing is inferred from the omitted detail.", "type": "string" } ] }, "ChangeAttributionView": { "description": "Which conditions behind a check's result the change brought, and which\n World found at the review's base revision. It sits beside the result and\n never changes it: a condition already at the base is still a condition.", "properties": { "complete_record": { "anyOf": [ { "$ref": "#/components/schemas/CompleteRecordView" }, { "type": "null" } ], "description": "Where every condition is recorded when some are omitted. Absent when\n `conditions` lists them all." }, "condition_count": { "description": "How many conditions World attributed, listed or not. Zero unless\n `status` is `COMPARED`.", "format": "uint32", "minimum": 0, "type": "integer" }, "conditions": { "description": "Every condition, each once, in World's order, never netted against\n another. Empty unless `status` is `COMPARED`, and empty when some are\n omitted: it never lists only some of them.", "items": { "$ref": "#/components/schemas/AttributedConditionView" }, "type": "array" }, "counts": { "description": "How many conditions there are of each change at each revision, over\n every condition, listed or not. Changes with none are left out.", "items": { "$ref": "#/components/schemas/ChangeCountView" }, "type": "array" }, "detail_code": { "description": "World's code for why it could not read that revision, such as\n `BASE_REVIEWED_TREE_NOT_DECLARED`. Present exactly when `status` is\n `UNAVAILABLE`.", "type": [ "string", "null" ] }, "listed_conditions": { "description": "The conditions a summary lists when some are omitted: the first ones\n in the order `counts` gives, each whole, at most 50 and always fewer\n than `condition_count`. Present exactly when `omitted_condition_count`\n is not zero.", "items": { "$ref": "#/components/schemas/AttributedConditionView" }, "type": [ "array", "null" ] }, "omitted_condition_count": { "description": "How many of those conditions this response does not list. Zero when\n the result kept World's attribution whole. Otherwise the result kept a\n summary: `listed_conditions` lists the first ones, `counts` is still\n exact, and World's recorded evaluation holds every condition.", "format": "uint32", "minimum": 0, "type": "integer" }, "revision": { "anyOf": [ { "$ref": "#/components/schemas/AttributedRevision" }, { "type": "null" } ], "description": "The revision World could not read. Present exactly when `status` is\n `UNAVAILABLE`." }, "status": { "allOf": [ { "$ref": "#/components/schemas/AttributionStatus" } ], "description": "Whether World compared both revisions, could not read one, or recorded\n an attribution this build cannot read." } }, "required": [ "status", "condition_count", "omitted_condition_count", "counts", "conditions" ], "type": "object" }, "ChangeCountView": { "description": "How many conditions are of one change at one revision.", "properties": { "change": { "allOf": [ { "$ref": "#/components/schemas/AttributedChange" } ], "description": "How the counted conditions relate to the review's base revision." }, "count": { "description": "How many conditions have this `change` at this `revision`, over every\n condition, listed or not.", "format": "uint32", "minimum": 0, "type": "integer" }, "revision": { "allOf": [ { "$ref": "#/components/schemas/AttributedRevision" } ], "description": "The revision that holds the counted conditions." } }, "required": [ "change", "revision", "count" ], "type": "object" }, "CheckLifecycle": { "description": "World's lifecycle disclosure for the evaluator version that answered, as\n the receipt recorded it. A deployment gate counts only `GATING` results\n (`DeterministicCoverage::gate_effective_status`), and only when it\n evaluates a deployment; the lifecycle alone permits or blocks nothing.", "oneOf": [ { "const": "GATING", "description": "Eligible to count toward a deployment gate. A receipt recorded before\n lifecycle disclosure reads as this, the meaning its decisions were\n made under.", "type": "string" }, { "const": "SHADOW", "description": "Recorded for review. A gate never counts it.", "type": "string" }, { "const": "QUARANTINED", "description": "Suspended after a recorded outcome contradicted it. A gate never\n counts it.", "type": "string" }, { "const": "RETIRED", "description": "Withdrawn. It takes part in no new evaluation.", "type": "string" }, { "const": "UNKNOWN", "description": "The receipt carries a disclosure this projection cannot read.", "type": "string" } ] }, "CommentAddressEvaluationView": { "description": "One stored post-merge judgment of a finding comment.", "properties": { "evaluated_at": { "description": "When the evaluation was made.", "format": "date-time", "type": "string" }, "outcome": { "allOf": [ { "$ref": "#/components/schemas/CommentAddressOutcome" } ], "description": "`ADDRESSED`, `NOT_ADDRESSED`, or `INCOMPLETE` when the merged code could not be judged." }, "reason": { "description": "Server-authored reason. Render as text.", "type": "string" } }, "required": [ "outcome", "reason", "evaluated_at" ], "type": "object" }, "CommentAddressOutcome": { "enum": [ "ADDRESSED", "NOT_ADDRESSED", "INCOMPLETE" ], "type": "string" }, "CommentReaction": { "enum": [ "THUMBS_UP", "THUMBS_DOWN", "LAUGH", "HOORAY", "CONFUSED", "HEART", "ROCKET", "EYES" ], "type": "string" }, "CommentReactionView": { "description": "One stored reaction on the finding's root comment.", "properties": { "actor_github_user_id": { "description": "The stable GitHub identity of whoever reacted.", "format": "int64", "type": "integer" }, "actor_login": { "description": "Provider text. Render as text.", "type": [ "string", "null" ] }, "github_comment_id": { "description": "The GitHub comment the reaction is on: the finding's root comment.", "format": "int64", "type": "integer" }, "reaction": { "allOf": [ { "$ref": "#/components/schemas/CommentReaction" } ], "description": "The reaction as GitHub names it." } }, "required": [ "github_comment_id", "actor_github_user_id", "reaction" ], "type": "object" }, "CompleteRecordView": { "description": "World's immutable record of the complete answer an omitted list comes\n from.", "properties": { "attribution_digest": { "description": "The `sha256:` digest of the complete attribution in that record.", "type": "string" }, "world_evaluation_id": { "description": "The evaluation World recorded, which holds every condition.", "type": "string" } }, "required": [ "world_evaluation_id", "attribution_digest" ], "type": "object" }, "CustomerAssessment": { "properties": { "checks": { "allOf": [ { "$ref": "#/components/schemas/CustomerChecks" } ], "description": "The deterministic World checks recorded for this assessment." }, "completed_at": { "description": "When the assessment completed. Null while it has not.", "format": "date-time", "type": [ "string", "null" ] }, "decision_presentation": { "anyOf": [ { "$ref": "#/components/schemas/CustomerDecision" }, { "type": "null" } ], "description": "The retained decision disclosure, which grants no deployment\n authorization. Absent when none is recorded and the review kind\n records no decision basis." }, "domains": { "description": "The risk domains the assessment evaluated, each with its status and\n reason, ordered by domain.", "items": { "$ref": "#/components/schemas/DomainView" }, "type": "array" }, "environment_display_name": { "description": "The display name of the environment this assessment covers.", "type": "string" }, "findings": { "description": "The findings this assessment recorded, `SERIOUS` first.", "items": { "$ref": "#/components/schemas/CustomerFinding" }, "type": "array" }, "id": { "description": "The assessment's ID.", "format": "uuid", "type": "string" }, "incompleteness_kind": { "description": "Why an `INCOMPLETE` assessment is incomplete: `NOT_CONFIGURED`,\n `POLICY_EXCLUDED`, `EVIDENCE_UNAVAILABLE`, `HYPOTHESES_UNRESOLVED` or\n `MODEL_BUDGET_EXHAUSTED`. Absent otherwise; an unclassified gap is not a\n complete assessment.", "type": [ "string", "null" ] }, "reason_codes": { "description": "The assessment gap codes the backend recorded. Absent on historical\n records.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "release_evidence_gap": { "description": "The typed gap the automatic release-set read recorded. Null when the\n read is pending, pinned a release, or was never attempted.", "type": [ "string", "null" ] }, "started_at": { "description": "When the assessment started. Null until it starts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "The assessment's recorded status, such as `RUNNING`, `COMPLETED` or\n `INCOMPLETE`.", "type": "string" } }, "required": [ "id", "environment_display_name", "status", "domains", "findings", "checks" ], "type": "object" }, "CustomerAssessmentDetail": { "properties": { "checks": { "allOf": [ { "$ref": "#/components/schemas/CustomerChecks" } ], "description": "The deterministic World checks recorded for this assessment." }, "completed_at": { "description": "When the assessment completed. Null while it has not.", "format": "date-time", "type": [ "string", "null" ] }, "decision_presentation": { "anyOf": [ { "$ref": "#/components/schemas/CustomerDecision" }, { "type": "null" } ], "description": "The retained decision disclosure, which grants no deployment\n authorization. Absent when none is recorded and the review kind\n records no decision basis." }, "domains": { "description": "The risk domains the assessment evaluated, each with its status and\n reason, ordered by domain.", "items": { "$ref": "#/components/schemas/DomainView" }, "type": "array" }, "environment_display_name": { "description": "The display name of the environment this assessment covers.", "type": "string" }, "findings": { "description": "The findings this assessment recorded, `SERIOUS` first.", "items": { "$ref": "#/components/schemas/CustomerFinding" }, "type": "array" }, "id": { "description": "The assessment's ID.", "format": "uuid", "type": "string" }, "incompleteness_kind": { "description": "Why an `INCOMPLETE` assessment is incomplete: `NOT_CONFIGURED`,\n `POLICY_EXCLUDED`, `EVIDENCE_UNAVAILABLE`, `HYPOTHESES_UNRESOLVED` or\n `MODEL_BUDGET_EXHAUSTED`. Absent otherwise; an unclassified gap is not a\n complete assessment.", "type": [ "string", "null" ] }, "reason_codes": { "description": "The assessment gap codes the backend recorded. Absent on historical\n records.", "items": { "type": "string" }, "type": [ "array", "null" ] }, "release_evidence_gap": { "description": "The typed gap the automatic release-set read recorded. Null when the\n read is pending, pinned a release, or was never attempted.", "type": [ "string", "null" ] }, "review_id": { "description": "The review this assessment belongs to.", "format": "uuid", "type": "string" }, "started_at": { "description": "When the assessment started. Null until it starts.", "format": "date-time", "type": [ "string", "null" ] }, "status": { "description": "The assessment's recorded status, such as `RUNNING`, `COMPLETED` or\n `INCOMPLETE`.", "type": "string" }, "subjects": { "description": "The review subjects this assessment's own release set authorized, plus\n each `PRIMARY` subject that carries no release authorization.", "items": { "$ref": "#/components/schemas/SubjectView" }, "type": "array" } }, "required": [ "review_id", "id", "environment_display_name", "status", "domains", "findings", "checks", "subjects" ], "type": "object" }, "CustomerCheck": { "properties": { "change_attribution": { "anyOf": [ { "$ref": "#/components/schemas/ChangeAttributionView" }, { "type": "null" } ], "description": "Which conditions behind the outcome the change brought and which were\n already at the review's base revision. It never changes the outcome:\n a condition already at the base is pre-existing, not safe. Absent for\n a check whose evaluator does not compare the two revisions." }, "detail": { "description": "Why World refused the check, or otherwise World's recorded explanation\n of the result. Null when neither is recorded.", "type": [ "string", "null" ] }, "evaluated_at": { "description": "When World evaluated this answer. A reused answer is evidence from\n this instant, which can precede the assessment.", "type": [ "string", "null" ] }, "lifecycle": { "allOf": [ { "$ref": "#/components/schemas/CheckLifecycle" } ], "description": "The lifecycle of the evaluator version that answered. It says whether\n a deployment gate could count this result, not whether one did." }, "name": { "description": "The check's readable name, derived from its key.", "type": "string" }, "outcome": { "description": "The outcome the receipt recorded, which is the outcome a deployment\n gate weighed: `READY`, `BLOCKED`, `UNRESOLVED`, `UNAVAILABLE`,\n `NOT_APPLICABLE` or `NOT_ASKED`. A verdict never rewrites it.", "type": "string" }, "unresolved_reason": { "anyOf": [ { "$ref": "#/components/schemas/UnresolvedReason" }, { "type": "null" } ], "description": "Why an `UNRESOLVED` check did not settle, as World's verdict gave it.\n Absent on every other outcome, and on an unresolved receipt whose\n verdict names none of these reasons." } }, "required": [ "name", "outcome", "lifecycle" ], "type": "object" }, "CustomerChecks": { "properties": { "families": { "description": "One entry per recorded check result, ordered by check key and version.\n Empty when no receipt exists.", "items": { "$ref": "#/components/schemas/CustomerCheck" }, "type": "array" }, "receipt_recorded": { "description": "Whether these checks come from an immutable deterministic coverage\n receipt. When false, no check result is recorded.", "type": "boolean" }, "status": { "description": "The receipt's status, or `PENDING`, `SUPERSEDED`, `STOPPED`,\n `NOT_ATTEMPTED` or `UNAVAILABLE` when no receipt exists.", "type": "string" } }, "required": [ "receipt_recorded", "status", "families" ], "type": "object" }, "CustomerDecision": { "properties": { "authority": { "allOf": [ { "$ref": "#/components/schemas/Authority" } ], "description": "Whether the decision is `ADVISORY` or comes from a `DEPLOYMENT_POLICY`." }, "availability": { "allOf": [ { "$ref": "#/components/schemas/Availability" } ], "description": "Whether a verified decision record is present, absent, legacy, failed,\n or too large for this projection." }, "basis": { "anyOf": [ { "$ref": "#/components/schemas/CustomerDecisionBasis" }, { "type": "null" } ], "description": "The permission, evidence classification and reason code of the\n verified recorded basis. Null when no verified basis is recorded." }, "gate_state": { "anyOf": [ { "$ref": "#/components/schemas/GateState" }, { "type": "null" } ], "description": "The local deployment gate state and any recorded override. Null unless\n the decision belongs to a deployment gate." } }, "required": [ "availability", "authority" ], "type": "object" }, "CustomerDecisionBasis": { "properties": { "evidence": { "allOf": [ { "$ref": "#/components/schemas/EvidenceView" } ], "description": "How the recorded basis classified its evidence." }, "permission": { "allOf": [ { "$ref": "#/components/schemas/PermissionView" } ], "description": "The permission the recorded basis reached: `PERMIT` or `BLOCK`." }, "reason_code": { "description": "The reason code the recorded basis gives for its permission.", "type": "string" } }, "required": [ "permission", "evidence", "reason_code" ], "type": "object" }, "CustomerEvidenceRef": { "properties": { "commit_sha": { "description": "The commit a file or commit reference reads. Null for other kinds, and\n for a file reference whose review recorded no head commit.", "type": [ "string", "null" ] }, "companion_repository": { "description": "The repository a `companion_repository_file` reference reads from.\n Null for every other kind.", "type": [ "string", "null" ] }, "end_line": { "description": "The last cited line of a file reference. Null when the reference names\n no end line or is not a file reference.", "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] }, "kind": { "description": "The reference's kind: `repository_file`, `companion_repository_file`,\n `commit`, `workflow_run`, `world_entity`, `deterministic_test`,\n `recorded_read` or `text`.", "type": "string" }, "label": { "description": "The reference's display label, such as a path with its line range. A\n recorded read or an unnamed World entity carries a fixed label, and a\n deterministic test carries its check's readable name.", "type": "string" }, "legacy_text": { "description": "The unstructured text of a `text` reference. Null for structured\n references and for recorded reads.", "type": [ "string", "null" ] }, "provenance_status": { "description": "How the reference was obtained: `VERIFIED_REPOSITORY_READ`,\n `PINNED_WORLD_ENTITY`, `EXECUTED_DETERMINISTIC_TEST`,\n `PROVIDER_REFERENCE`, `RECORDED_READ` or `LEGACY_UNSTRUCTURED`.", "type": "string" }, "repository_path": { "description": "The cited file's path for a file reference. Null for every other kind.", "type": [ "string", "null" ] }, "start_line": { "description": "The first cited line of a file reference. Null when the reference cites\n no line or is not a file reference.", "format": "uint32", "minimum": 0, "type": [ "integer", "null" ] }, "url": { "description": "The link the reference resolves to. Null when it resolves to none or\n the review's repository or head commit is unknown.", "type": [ "string", "null" ] }, "workflow_attempt": { "description": "The run attempt of a `workflow_run` reference. Null when the reference\n names no attempt or is another kind.", "format": "int32", "type": [ "integer", "null" ] }, "workflow_run_id": { "description": "The GitHub Actions run ID of a `workflow_run` reference. Null for every\n other kind.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "kind", "label", "provenance_status" ], "type": "object" }, "CustomerFinding": { "properties": { "causal_graph": { "anyOf": [ { "$ref": "#/components/schemas/FindingCausalGraphView" }, { "type": "null" } ], "description": "The typed causal graph the reviewer supplied for an ordering or\n reachability finding. Null when the finding carries none." }, "claim": { "description": "What the reviewer states is wrong.", "type": "string" }, "comment_evaluation": { "anyOf": [ { "$ref": "#/components/schemas/CommentAddressEvaluationView" }, { "type": "null" } ], "description": "The post-merge judgment of whether the finding comment was addressed.\n It is not a finding decision; null when none is recorded." }, "comment_reactions": { "description": "Emoji reactions stored on the Proofline finding comment. They are not a\n finding decision.", "items": { "$ref": "#/components/schemas/CommentReactionView" }, "type": "array" }, "evidence_class": { "anyOf": [ { "$ref": "#/components/schemas/FindingEvidenceClass" }, { "type": "null" } ], "description": "The kind of proof the finding rests on, derived from the typed evidence\n it cites. Null on findings recorded before the class existed." }, "evidence_refs": { "description": "The references the finding cites, resolved as the pull request comment\n resolves them.", "items": { "$ref": "#/components/schemas/CustomerEvidenceRef" }, "type": "array" }, "github_comment_url": { "description": "The inline GitHub comment published for this occurrence of the finding.\n Null when none was published; earlier runs are never used as a fallback.", "type": [ "string", "null" ] }, "id": { "description": "The finding's ID.", "format": "uuid", "type": "string" }, "impact": { "description": "The consequence the reviewer states the claim has.", "type": "string" }, "latest_validation": { "anyOf": [ { "$ref": "#/components/schemas/CustomerFindingValidation" }, { "type": "null" } ], "description": "The latest decision on the finding's series, with who made it, where\n and when. Null when no decision is recorded." }, "lifecycle_state": { "description": "The finding's recorded lifecycle state: `NEW`, `UNCHANGED`, `RESOLVED`\n or `REINTRODUCED`.", "type": "string" }, "remediation": { "description": "The reviewer's proposed fix. Null when it proposed none.", "type": [ "string", "null" ] }, "risk_domain": { "description": "The risk domain the reviewer assigned to the finding.", "type": "string" }, "severity": { "description": "`SERIOUS` or `WARNING`.", "type": "string" }, "supporting_evidence": { "anyOf": [ { "$ref": "#/components/schemas/FindingSupport" }, { "type": "null" } ], "description": "The verdict explanation and evidence of the supported hypothesis that\n produced this finding. Null when the finding links no supported\n hypothesis." }, "symbols": { "description": "The code identifiers the reviewer declared in the finding's prose, in\n declaration order, so a reader can set each as code.", "items": { "type": "string" }, "type": "array" }, "thread_observation": { "anyOf": [ { "$ref": "#/components/schemas/ThreadObservationView" }, { "type": "null" } ], "description": "The latest observation of the finding's GitHub thread state. It is not\n a finding decision; null when none is recorded." }, "validation": { "description": "The latest decision on the finding, the same value `latest_validation`\n carries. Null when no decision is recorded.", "type": [ "string", "null" ] } }, "required": [ "id", "severity", "risk_domain", "claim", "impact", "symbols", "lifecycle_state", "evidence_refs", "comment_reactions" ], "type": "object" }, "CustomerFindingValidation": { "properties": { "actor_github_user_id": { "description": "The actor's stable GitHub user ID. Null for the automatic decision.", "format": "int64", "type": [ "integer", "null" ] }, "actor_login": { "description": "The actor's GitHub login, a display label to render as text. Null for\n the automatic decision.", "type": [ "string", "null" ] }, "covering_author_kind": { "description": "For `ALREADY_COVERED`, `HUMAN` or `BOT`. Null for every other decision.", "type": [ "string", "null" ] }, "covering_author_login": { "description": "For `ALREADY_COVERED`, the login of whoever wrote the covering comment,\n to render as text. Null for every other decision.", "type": [ "string", "null" ] }, "covering_comment_created_at": { "description": "For `ALREADY_COVERED`, when the covering comment was written. Null for\n every other decision.", "format": "date-time", "type": [ "string", "null" ] }, "github_comment_url": { "description": "The comment that carried a decision made on GitHub, or, for\n `ALREADY_COVERED`, the other reviewer's comment the decision rests on.", "type": [ "string", "null" ] }, "recorded_at": { "description": "When Proofline recorded the decision.", "format": "date-time", "type": "string" }, "source": { "description": "Where the decision came from: `UI` for the app's assessment controls,\n `GITHUB_COMMENT` for a pull request comment, or `PROOFLINE` for the\n automatic `ALREADY_COVERED` decision.", "type": "string" }, "validation": { "description": "The decision: `CONFIRMED`, `DISMISSED`, `FIXED`, `ACCEPTED_RISK` or\n `ALREADY_COVERED`.", "type": "string" } }, "required": [ "validation", "recorded_at", "source" ], "type": "object" }, "CustomerReviewDetail": { "properties": { "actions": { "allOf": [ { "$ref": "#/components/schemas/ReviewActions" } ], "description": "Which review actions the caller may take now." }, "assessment_count": { "description": "How many environment assessments this review has.", "format": "int64", "type": "integer" }, "assessments": { "description": "The environment assessments this review recorded.", "items": { "$ref": "#/components/schemas/CustomerAssessment" }, "type": "array" }, "base_branch_commit_sha": { "description": "The base branch tip GitHub reported when the review was triggered,\n display metadata that differs from `base_commit_sha` when the base\n branch moved after the branch point.", "type": [ "string", "null" ] }, "base_commit_sha": { "description": "The base revision the review compares against; for a pull request, the\n merge base of its head and base branch. Null until pinned, and for a\n first deployment.", "type": [ "string", "null" ] }, "base_commit_url": { "description": "The GitHub page for `base_commit_sha`. Null when that commit or the\n repository is unknown.", "type": [ "string", "null" ] }, "base_ref": { "description": "The pull request's base branch name as last recorded from GitHub, for\n orientation only. Null when no pull request state is recorded.", "type": [ "string", "null" ] }, "check_run_url": { "description": "The GitHub check run Proofline published for this review. Null when\n none was published.", "type": [ "string", "null" ] }, "compare_url": { "description": "The GitHub comparison of the base and head commits. Null unless both\n are pinned and the repository is known, and for a patch review, whose\n head GitHub does not have.", "type": [ "string", "null" ] }, "completed_at": { "description": "When the review reached a terminal status. Absent while it is still pending or running.", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the review was created.", "format": "date-time", "type": "string" }, "current_head_commit_sha": { "description": "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.", "type": [ "string", "null" ] }, "diff_stats": { "anyOf": [ { "$ref": "#/components/schemas/ReviewDiffStats" }, { "type": "null" } ], "description": "Line totals from this run's pinned comparison. Null until recorded, or\n when the provider's changed-file list was incomplete." }, "environment_display_names": { "description": "Display names of this review's assessed environments, not current repository links.", "items": { "type": "string" }, "type": "array" }, "finding_count": { "description": "How many findings this review's assessments recorded, across all of them.", "format": "int64", "type": "integer" }, "head_commit_sha": { "description": "The head commit this review is pinned to. For a patch review, the\n revision ID Proofline derives from its base commit and patch digest,\n which is not a commit. Absent when the review recorded none.", "type": [ "string", "null" ] }, "head_commit_url": { "description": "The exact revision reviewed. A commit URL, never a branch URL: the\n branch moves, the reviewed input does not. Absent for a patch review.", "type": [ "string", "null" ] }, "head_ref": { "description": "The pull request's head branch name as last recorded from GitHub, for\n orientation only. Null when no pull request state is recorded.", "type": [ "string", "null" ] }, "id": { "description": "The review's identifier.", "format": "uuid", "type": "string" }, "kind": { "description": "`PULL_REQUEST`, `DEPLOYMENT` or `PATCH`, a review of local changes\n sent as a patch.", "type": "string" }, "merge_gate": { "anyOf": [ { "$ref": "#/components/schemas/PullRequestMergeGate" }, { "type": "null" } ], "description": "The deterministic policy for this exact repository/head, when opted in.\n Its captured review owner and GitHub bypass remain separate history." }, "open_items": { "anyOf": [ { "$ref": "#/components/schemas/OpenItemsView" }, { "type": "null" } ], "description": "What Proofline still has open for the reviewed head, counted from the\n current finding decisions. Absent while the review is `PENDING` or\n `RUNNING`." }, "open_items_observation": { "anyOf": [ { "$ref": "#/components/schemas/ReviewOpenItems" }, { "type": "null" } ], "description": "Dated PR counts with head, evaluated-scope and bounded thread proof.\n Absent when that observation is unavailable; scalar counts remain separate." }, "public_key": { "description": "The review's stable public address: `rev_` followed by its identifier without hyphens.", "type": "string" }, "publication": { "description": "Whether the review reached the pull request: `PUBLISHED`, `WITHHELD`,\n `PUBLICATION_REQUESTED` or `PUBLICATION_REFUSED`. A review run from\n Proofline is withheld until somebody publishes it.", "type": "string" }, "publication_detail": { "description": "Why a publication was refused, or how one failed. Server text.", "type": [ "string", "null" ] }, "pull_request_author_avatar_url": { "description": "Provider-supplied avatar URL. Login-derived `.png` URLs do not work for\n GitHub App bot accounts and are not portable across GitHub hosts.", "type": [ "string", "null" ] }, "pull_request_author_github_user_id": { "description": "The author's stable GitHub user id: identity for profile lookups,\n never display text. Absent when GitHub named no author.", "format": "int64", "type": [ "integer", "null" ] }, "pull_request_author_login": { "description": "Provider display metadata for the pull request author, not the rerun requester.", "type": [ "string", "null" ] }, "pull_request_author_url": { "description": "The author's profile on the deployment's GitHub host. Absent when no author login is known.", "type": [ "string", "null" ] }, "pull_request_number": { "description": "The pull request number. Absent for a deployment or patch review.", "format": "int64", "type": [ "integer", "null" ] }, "pull_request_state": { "description": "Current provider state of the pull request: `OPEN`, `CLOSED`, or\n `MERGED`. Absent for deployment reviews or a missing projection.", "type": [ "string", "null" ] }, "pull_request_title": { "description": "The pull request's title as provider state last reported it, so it\n names the change rather than only numbering it. Untrusted text:\n renderers must treat it as text, never markup.", "type": [ "string", "null" ] }, "pull_request_url": { "description": "The pull request on GitHub. Absent for a deployment review or when the repository is unknown.", "type": [ "string", "null" ] }, "related_reviews": { "description": "Every other run for this pull request the caller can see, plus reviews\n joined to this one by supersession or rerun.", "items": { "$ref": "#/components/schemas/RelatedReview" }, "type": "array" }, "repository_full_name": { "description": "The repository's `owner/name`. Absent when the review names no repository.", "type": [ "string", "null" ] }, "repository_id": { "description": "The review's repository. Set only on a single-review read, and absent there when the review names no repository.", "format": "uuid", "type": [ "string", "null" ] }, "repository_name": { "description": "The repository's name within its owner. Absent when the review names no repository.", "type": [ "string", "null" ] }, "repository_url": { "description": "The repository on GitHub. Absent when the deployment's web base\n cannot be joined with the stored name.", "type": [ "string", "null" ] }, "requested_by": { "anyOf": [ { "$ref": "#/components/schemas/ActorView" }, { "type": "null" } ], "description": "Who asked for this review, for a review a person requested. Null on\n automatic reviews and on reviews recorded before requesters were." }, "review_comment_url": { "description": "The pull request review Proofline submitted for this review. Null when\n it submitted none.", "type": [ "string", "null" ] }, "review_retracted_at": { "description": "When a submitted pull request review was marked retracted, a marker\n only older versions set. Null otherwise.", "format": "date-time", "type": [ "string", "null" ] }, "run_number": { "description": "One-based, append-only ordinal within one repository pull request.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "description": "The review's lifecycle status: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED` or `EXCLUDED`.", "type": "string" }, "stoppable": { "description": "Whether the stop action applies: the review is `PENDING` or `RUNNING`\n and decides no deployment gate. It says nothing about the caller's\n permission.", "type": "boolean" }, "stopped_at": { "description": "When the review was stopped. Null unless it was stopped.", "format": "date-time", "type": [ "string", "null" ] }, "stopped_by": { "anyOf": [ { "$ref": "#/components/schemas/ActorView" }, { "type": "null" } ], "description": "Who stopped this review, for a `STOPPED` review whose stop recorded its\n actor. Null otherwise." }, "stopped_from": { "description": "Where the review was stopped: `PROOFLINE` or `PULL_REQUEST`. Null unless\n the stop recorded it.", "type": [ "string", "null" ] }, "subjects": { "description": "What this review covers: the revision under review and any companion\n repositories, workflow runs, artifacts or deployments.", "items": { "$ref": "#/components/schemas/SubjectView" }, "type": "array" }, "superseded_by_review_id": { "description": "The newer review that superseded this one. Null when none did or the\n caller cannot see it.", "format": "uuid", "type": [ "string", "null" ] }, "trigger_origin": { "description": "Who asked for this review: `AUTOMATIC`, `COMMAND`, `RERUN`, `MANUAL`,\n or `UNKNOWN` for a trigger key this build does not recognise.", "type": "string" } }, "required": [ "id", "public_key", "kind", "status", "assessment_count", "environment_display_names", "finding_count", "trigger_origin", "publication", "created_at", "stoppable", "related_reviews", "subjects", "assessments", "actions" ], "type": "object" }, "Dataset": { "enum": [ "reviews", "finding_outcomes", "finding_validations", "spend", "findings" ], "type": "string" }, "DomainView": { "properties": { "domain": { "description": "The risk domain this evaluation covers.", "type": "string" }, "reason": { "description": "Why the domain was considered or skipped, as recorded with the evaluation.", "type": "string" }, "status": { "description": "`CONSIDERED` or `SKIPPED`.", "type": "string" } }, "required": [ "domain", "status", "reason" ], "type": "object" }, "EvidenceView": { "enum": [ "REQUIRED_PROPERTIES_ESTABLISHED", "INCOMPLETE", "NO_APPLICABLE_OBLIGATIONS" ], "type": "string" }, "ExportEvidenceKind": { "enum": [ "repository_file", "repository_file_at_commit", "companion_repository_file", "commit", "workflow_run", "world_entity", "deterministic_test", "recorded_read", "text" ], "type": "string" }, "ExportEvidenceRef": { "properties": { "id": { "description": "Stable opaque occurrence-local identity, independent of evidence values.", "type": "string" }, "kind": { "allOf": [ { "$ref": "#/components/schemas/ExportEvidenceKind" } ], "description": "The recorded reference kind, or `text` for a kind this export does not recognize." } }, "required": [ "kind", "id" ], "type": "object" }, "ExportFindingLifecycle": { "enum": [ "NEW", "UNCHANGED", "RESOLVED", "REINTRODUCED" ], "type": "string" }, "ExportFindingSeverity": { "enum": [ "WARNING", "SERIOUS" ], "type": "string" }, "ExportReviewKind": { "enum": [ "PULL_REQUEST", "DEPLOYMENT", "PATCH" ], "type": "string" }, "ExportReviewStatus": { "enum": [ "PENDING", "RUNNING", "COMPLETED", "INCOMPLETE", "FAILED", "SUPERSEDED", "STOPPED", "EXCLUDED" ], "type": "string" }, "ExportRow": { "anyOf": [ { "$ref": "#/components/schemas/ReviewsExportRow" }, { "$ref": "#/components/schemas/FindingOutcomesExportRow" }, { "$ref": "#/components/schemas/FindingValidationsExportRow" }, { "$ref": "#/components/schemas/SpendExportRow" }, { "$ref": "#/components/schemas/FindingsExportRow" } ], "description": "The closed row vocabulary of the existing raw-stream export operation." }, "ExportValidation": { "enum": [ "UNKNOWN", "CONFIRMED", "DISMISSED", "FIXED", "ACCEPTED_RISK", "ALREADY_COVERED" ], "type": "string" }, "ExportValidationSource": { "enum": [ "ui", "github_comment", "proofline" ], "type": "string" }, "FileProjection": { "properties": { "depth": { "description": "The code-inspection depth retained by the plan.", "type": "string" }, "passes": { "description": "The review passes bound to this file.", "items": { "type": "string" }, "type": "array" }, "path": { "description": "Repository-relative path retained by the routing plan.", "type": "string" } }, "required": [ "path", "depth", "passes" ], "type": "object" }, "FilterChoice": { "properties": { "id": { "description": "The repository or environment ID to pass as the filter value.", "format": "uuid", "type": "string" }, "name": { "description": "The repository's full name or the environment's display name.", "type": "string" } }, "required": [ "id", "name" ], "type": "object" }, "FindingCausalEdgeView": { "properties": { "from": { "description": "The `id` of the node the edge starts at.", "type": "string" }, "label": { "description": "What the relation is. Model-authored text, and absent when the reviewer gave none.", "type": [ "string", "null" ] }, "to": { "description": "The `id` of the node the edge ends at.", "type": "string" } }, "required": [ "from", "to" ], "type": "object" }, "FindingCausalGraphView": { "properties": { "edges": { "description": "Directed relations between nodes. An edge can name a node identifier that no node carries.", "items": { "$ref": "#/components/schemas/FindingCausalEdgeView" }, "type": "array" }, "nodes": { "description": "The actors in the finding, as the reviewer named them.", "items": { "$ref": "#/components/schemas/FindingCausalNodeView" }, "type": "array" } }, "required": [ "nodes", "edges" ], "type": "object" }, "FindingCausalNodeView": { "properties": { "id": { "description": "The reviewer-assigned node identifier that edges refer to. Model-authored text.", "type": "string" }, "label": { "description": "What the node is. Model-authored text: render as text.", "type": "string" }, "role": { "description": "One of `change`, `dependency`, `failure`, `blocked` or `ok`, or empty; a value outside that set is returned as recorded.", "type": "string" } }, "required": [ "id", "label", "role" ], "type": "object" }, "FindingEvidenceClass": { "oneOf": [ { "enum": [ "ANALYZER_BACKED", "CODE_ONLY" ], "type": "string" }, { "const": "WORLD_EVIDENCED", "description": "A World entity or deterministic World evaluation at the pinned snapshot.", "type": "string" }, { "const": "EXPERIMENT_BACKED", "description": "A read of the deployed environment the sandbox recorded.", "type": "string" } ] }, "FindingOutcomesCount": { "properties": { "count": { "description": "Published finding series in the group whose series disposition is `RESOLVED_BY_PUSH`.", "format": "int64", "type": "integer" }, "drilldown": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesDrilldown" } ], "description": "The query that lists the series behind `count`." } }, "required": [ "count", "drilldown" ], "type": "object" }, "FindingOutcomesDrilldown": { "properties": { "group_key": { "description": "The `group_key` query value that limits the listed series to this count's group.", "type": "string" }, "outcome": { "anyOf": [ { "$ref": "#/components/schemas/FindingOutcomesOutcome" }, { "type": "null" } ], "description": "The `outcome` query value for an `outcome` selector, and null for every other\n selector." }, "post_merge": { "anyOf": [ { "$ref": "#/components/schemas/FindingOutcomesPostMergeOutcome" }, { "type": "null" } ], "description": "The `post_merge` query value for a `post_merge` selector, and null for every other\n selector." }, "selector": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesSelector" } ], "description": "The `selector` query value that lists the series behind this count." } }, "required": [ "selector", "group_key" ], "type": "object" }, "FindingOutcomesExportRow": { "description": "Exact shared aggregate counts for one admitted group and requested window.", "properties": { "code_changed": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesCount" } ], "description": "Published series whose series disposition is `RESOLVED_BY_PUSH`." }, "dataset_version": { "description": "The row contract version, always `1`.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "external_validation_denominator": { "description": "Human-validated series; excludes automatic coverage and unrecorded outcomes.", "format": "int64", "type": "integer" }, "from": { "description": "The inclusive start of the requested first-publication window.", "format": "date-time", "type": "string" }, "group_by": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesGroupBy" } ], "description": "The dimension that defines this row's group." }, "key": { "description": "The grouping value: a repository or environment ID, a risk domain, a severity or a\n review kind, as `group_by` selects.", "type": "string" }, "limitations": { "description": "Gaps in publication history that keep findings outside these counts; they mean\n missing history, not zero findings.", "items": { "type": "string" }, "type": "array" }, "name": { "description": "The group's display name: the repository's full name (or `Repository` and its ID when\n no name is recorded), the environment's display name, or otherwise `key`.", "type": "string" }, "organization_id": { "description": "The organization whose findings are counted.", "format": "uuid", "type": "string" }, "outcomes": { "description": "One count per outcome, always all six `FindingOutcomesOutcome` values in a fixed order.", "items": { "$ref": "#/components/schemas/FindingOutcomesOutcomeCount" }, "type": "array" }, "post_merge": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesPostMergeCounts" } ], "description": "Published series counted by their latest post-merge comment-address evaluation." }, "published": { "description": "Finding series in the group whose first publication falls inside the window.", "format": "int64", "type": "integer" }, "to": { "description": "The exclusive end of the requested first-publication window.", "format": "date-time", "type": "string" } }, "required": [ "dataset_version", "organization_id", "from", "to", "group_by", "external_validation_denominator", "key", "name", "published", "outcomes", "code_changed", "post_merge", "limitations" ], "type": "object" }, "FindingOutcomesGroupBy": { "enum": [ "repository", "environment", "risk_domain", "severity", "subject_kind" ], "type": "string" }, "FindingOutcomesOutcome": { "enum": [ "FIXED", "CONFIRMED", "ACCEPTED_RISK", "DISMISSED", "ALREADY_COVERED", "NO_RECORDED_OUTCOME" ], "type": "string" }, "FindingOutcomesOutcomeCount": { "properties": { "count": { "description": "Published finding series in the group whose latest qualifying outcome is `outcome`.", "format": "int64", "type": "integer" }, "drilldown": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesDrilldown" } ], "description": "The query that lists the series behind `count`." }, "outcome": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesOutcome" } ], "description": "The outcome counted, where `NO_RECORDED_OUTCOME` means the series has no qualifying\n validation." }, "validation_sources": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesValidationSources" } ], "description": "`count` split by where the outcome was recorded; a `NO_RECORDED_OUTCOME` count has no\n source." } }, "required": [ "outcome", "count", "validation_sources", "drilldown" ], "type": "object" }, "FindingOutcomesPostMergeCount": { "properties": { "count": { "description": "Published finding series in the group whose latest evaluation recorded `outcome`.", "format": "int64", "type": "integer" }, "drilldown": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesDrilldown" } ], "description": "The query that lists the series behind `count`." }, "outcome": { "allOf": [ { "$ref": "#/components/schemas/FindingOutcomesPostMergeOutcome" } ], "description": "The outcome of the series' latest comment-address evaluation." } }, "required": [ "outcome", "count", "drilldown" ], "type": "object" }, "FindingOutcomesPostMergeCounts": { "properties": { "judged": { "description": "Series with a retained evaluation, rather than all published series.", "format": "int64", "type": "integer" }, "outcomes": { "description": "One count per post-merge outcome, always `ADDRESSED`, `NOT_ADDRESSED` and `INCOMPLETE`\n in that order.", "items": { "$ref": "#/components/schemas/FindingOutcomesPostMergeCount" }, "type": "array" } }, "required": [ "judged", "outcomes" ], "type": "object" }, "FindingOutcomesPostMergeOutcome": { "enum": [ "ADDRESSED", "NOT_ADDRESSED", "INCOMPLETE" ], "type": "string" }, "FindingOutcomesSelector": { "enum": [ "outcome", "code_changed", "post_merge" ], "type": "string" }, "FindingOutcomesValidationSources": { "properties": { "console": { "description": "Series whose outcome comes from a validation recorded in the console.", "format": "int64", "type": "integer" }, "github_reply": { "description": "Series whose outcome comes from a validation recorded by a GitHub comment reply.", "format": "int64", "type": "integer" }, "proofline": { "description": "Series whose outcome is `ALREADY_COVERED`, recorded by Proofline itself.", "format": "int64", "type": "integer" } }, "required": [ "console", "github_reply", "proofline" ], "type": "object" }, "FindingSupport": { "properties": { "evidence_refs": { "description": "The references the hypothesis cites for its verdict.", "items": { "$ref": "#/components/schemas/CustomerEvidenceRef" }, "type": "array" }, "explanation": { "anyOf": [ { "$ref": "#/components/schemas/UntrustedText" }, { "type": "null" } ], "description": "Why the hypothesis reached its verdict, as recorded at resolution. Null\n when no explanation is recorded." } }, "required": [ "evidence_refs" ], "type": "object" }, "FindingValidationsExportRow": { "description": "One append-only validation, including its recorded actor display metadata.\n Missing historical actors stay absent; the export does not infer identity.", "properties": { "actor_github_user_id": { "description": "The GitHub user ID captured as the actor, null when none was captured.", "format": "int64", "type": [ "integer", "null" ] }, "actor_login": { "description": "The GitHub login captured as display metadata at validation time, null when none was\n captured.", "type": [ "string", "null" ] }, "actor_user_id": { "description": "The Proofline user captured as the actor, null when none was captured.", "format": "uuid", "type": [ "string", "null" ] }, "created_at": { "description": "When the validation was recorded; the export window filters on this time.", "format": "date-time", "type": "string" }, "dataset_version": { "description": "The row contract version, always `1`.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "environment_id": { "description": "The environment of the assessment that recorded the finding.", "format": "uuid", "type": "string" }, "expires_at": { "description": "When the decision expires, null when it records no expiry.", "format": "date-time", "type": [ "string", "null" ] }, "finding_id": { "description": "The finding occurrence the validation applies to.", "format": "uuid", "type": "string" }, "organization_id": { "description": "The organization that owns the finding.", "format": "uuid", "type": "string" }, "repository_id": { "description": "The review's primary repository, null when the review records none.", "format": "uuid", "type": [ "string", "null" ] }, "review_id": { "description": "The review whose assessment recorded the finding.", "format": "uuid", "type": "string" }, "source": { "allOf": [ { "$ref": "#/components/schemas/ExportValidationSource" } ], "description": "Where the decision was recorded: `ui` or `github_comment` for a person, `proofline` for\n automatic coverage." }, "validation": { "allOf": [ { "$ref": "#/components/schemas/ExportValidation" } ], "description": "The recorded decision, including legacy `UNKNOWN` values." }, "validation_id": { "description": "The stable ID of this validation record.", "format": "uuid", "type": "string" } }, "required": [ "dataset_version", "organization_id", "validation_id", "finding_id", "review_id", "environment_id", "validation", "source", "created_at" ], "type": "object" }, "FindingsExportRow": { "description": "One immutable finding occurrence. Reference payloads and evidence values stay private.", "properties": { "assessment_id": { "description": "The environment assessment that recorded the finding.", "format": "uuid", "type": "string" }, "claim": { "description": "The finding's claim, with supported credential shapes masked as ``.", "type": "string" }, "created_at": { "description": "When the finding was recorded; the export window filters on this time.", "format": "date-time", "type": "string" }, "dataset_version": { "description": "The row contract version, always `1`.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "environment_id": { "description": "The environment the assessment covers.", "format": "uuid", "type": "string" }, "evidence_refs": { "description": "The finding's evidence references in recorded order, each reduced to a kind and an\n opaque ID; an empty list means the finding records none.", "items": { "$ref": "#/components/schemas/ExportEvidenceRef" }, "type": "array" }, "finding_id": { "description": "The stable ID of this finding occurrence.", "format": "uuid", "type": "string" }, "impact": { "description": "The finding's stated impact, with supported credential shapes masked.", "type": "string" }, "lifecycle_state": { "allOf": [ { "$ref": "#/components/schemas/ExportFindingLifecycle" } ], "description": "The occurrence's recorded lifecycle state relative to earlier occurrences." }, "organization_id": { "description": "The organization that owns the finding.", "format": "uuid", "type": "string" }, "remediation": { "description": "The suggested remediation with credential shapes masked, null when none is recorded.", "type": [ "string", "null" ] }, "repository_id": { "description": "The review's primary repository, null when the review records none.", "format": "uuid", "type": [ "string", "null" ] }, "review_id": { "description": "The review whose assessment recorded the finding.", "format": "uuid", "type": "string" }, "risk_domain": { "description": "The risk domain the finding is recorded under.", "type": "string" }, "series_id": { "description": "The finding series this occurrence belongs to, null when it belongs to none.", "format": "uuid", "type": [ "string", "null" ] }, "severity": { "allOf": [ { "$ref": "#/components/schemas/ExportFindingSeverity" } ], "description": "The finding's recorded severity." } }, "required": [ "dataset_version", "organization_id", "finding_id", "review_id", "assessment_id", "environment_id", "risk_domain", "severity", "lifecycle_state", "claim", "impact", "evidence_refs", "created_at" ], "type": "object" }, "GateState": { "properties": { "override_record": { "anyOf": [ { "$ref": "#/components/schemas/Override" }, { "type": "null" } ], "description": "Recorded override authorization, not confirmation of provider delivery." }, "status": { "description": "Local gate state. ALLOWED/BLOCKED can precede provider delivery.\n This field does not confirm that GitHub released or blocked a run.", "type": "string" } }, "required": [ "status" ], "type": "object" }, "GateStatus": { "enum": [ "REQUESTED", "EVALUATING", "ALLOWED", "BLOCKED", "BYPASSED", "SUPERSEDED" ], "type": "string" }, "NotAssessedView": { "properties": { "environment_display_name": { "description": "The display name of the environment whose assessment is not\n `COMPLETED`.", "type": "string" }, "incompleteness_kind": { "description": "The assessment's recorded gap class. Absent is an unclassified gap,\n never a complete assessment.", "type": [ "string", "null" ] } }, "required": [ "environment_display_name" ], "type": "object" }, "OpenFindingCounts": { "properties": { "serious": { "description": "Finding series with `SERIOUS` severity that are unresolved and not\n under an unexpired dismissal or risk acceptance.", "format": "uint64", "minimum": 0, "type": "integer" }, "warning": { "description": "Finding series with `WARNING` severity that are unresolved and not\n under an unexpired dismissal or risk acceptance.", "format": "uint64", "minimum": 0, "type": "integer" } }, "required": [ "serious", "warning" ], "type": "object" }, "OpenItemEnvironment": { "properties": { "display_name": { "description": "The environment's display name.", "type": "string" }, "environment_id": { "description": "The environment whose assessment is not complete.", "format": "uuid", "type": "string" }, "reason": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsGapReason" } ], "description": "Why the assessment is not complete, derived from its status and\n recorded gap class; `UNKNOWN` when neither names a cause." }, "status": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsReviewStatus" } ], "description": "The assessment's recorded status." } }, "required": [ "environment_id", "display_name", "status", "reason" ], "type": "object" }, "OpenItemsGapReason": { "enum": [ "NOT_STARTED", "IN_PROGRESS", "NOT_CONFIGURED", "POLICY_EXCLUDED", "EVIDENCE_UNAVAILABLE", "HYPOTHESES_UNRESOLVED", "MODEL_BUDGET_EXHAUSTED", "FAILED", "STOPPED", "UNKNOWN" ], "type": "string" }, "OpenItemsHeadState": { "enum": [ "CURRENT", "OUTDATED", "UNKNOWN" ], "type": "string" }, "OpenItemsReviewStatus": { "enum": [ "PENDING", "RUNNING", "COMPLETED", "INCOMPLETE", "FAILED", "SUPERSEDED", "STOPPED", "EXCLUDED", "UNKNOWN" ], "type": "string" }, "OpenItemsThreadUnknown": { "enum": [ "GITHUB_UNAVAILABLE", "READ_LIMIT_EXCEEDED", "TRUNCATED", "RECORDED_THREAD_MISSING", "REPOSITORY_UNAVAILABLE" ], "type": "string" }, "OpenItemsThreads": { "oneOf": [ { "properties": { "observed_at": { "format": "date-time", "type": "string" }, "status": { "const": "KNOWN", "type": "string" }, "unresolved_count": { "format": "uint64", "minimum": 0, "type": "integer" } }, "required": [ "status", "unresolved_count", "observed_at" ], "type": "object" }, { "properties": { "reason": { "$ref": "#/components/schemas/OpenItemsThreadUnknown" }, "status": { "const": "UNKNOWN", "type": "string" } }, "required": [ "status", "reason" ], "type": "object" } ] }, "OpenItemsView": { "description": "Recorded unresolved findings, accepted risks and assessment gaps.\n Coverage and notification suppression do not resolve a finding. These\n scalar counts make no claim about current heads, evaluated scope or threads.", "properties": { "accepted_risks": { "description": "Finding series whose current decision is an unexpired `ACCEPTED_RISK`.", "format": "uint", "minimum": 0, "type": "integer" }, "not_assessed": { "description": "Recorded assessment gaps, including explicit policy exclusions.", "items": { "$ref": "#/components/schemas/NotAssessedView" }, "type": "array" }, "open_findings": { "description": "Unresolved recorded finding series, including notification-suppressed\n findings, decisions whose dismissal or risk acceptance expired, and\n earlier published series of the pull request that this review did not\n find again.", "format": "uint", "minimum": 0, "type": "integer" }, "serious_findings": { "description": "The `SERIOUS` findings among `open_findings`.", "format": "uint", "minimum": 0, "type": "integer" } }, "required": [ "open_findings", "serious_findings", "accepted_risks", "not_assessed" ], "type": "object" }, "Outcome": { "enum": [ "ALLOW", "BLOCK" ], "type": "string" }, "Override": { "properties": { "comment": { "description": "The comment recorded with the approval, truncated past 8000\n characters.", "type": [ "string", "null" ] }, "github_environment_id": { "description": "The GitHub environment ID the approval applied to.", "format": "int64", "type": "integer" }, "github_user_id": { "description": "The GitHub user ID of the person whose GitHub deployment approval\n overrode the gate.", "format": "int64", "type": "integer" }, "github_user_login": { "description": "That person's GitHub login as recorded with the approval, a display\n label truncated past 128 characters.", "type": "string" } }, "required": [ "github_user_id", "github_user_login", "github_environment_id" ], "type": "object" }, "PassProjection": { "properties": { "model_binding": { "description": "Symbolic configuration binding, not a historical model identity.", "type": "string" }, "name": { "description": "Pass name from the closed routing schema.", "type": "string" } }, "required": [ "name", "model_binding" ], "type": "object" }, "PatchReviewRequest": { "additionalProperties": false, "description": "Local changes to review: a unified diff against a commit GitHub has.", "properties": { "base_commit_sha": { "description": "The full 40-character commit the patch applies to. GitHub must have\n it in this repository.", "type": "string" }, "patch": { "description": "The changes as `git diff --no-ext-diff --no-color ` prints them,\n at most 5 MiB and 3000 files. Text changes only: binary changes,\n symbolic links and submodules are refused.", "type": "string" } }, "required": [ "base_commit_sha", "patch" ], "type": "object" }, "PatchReviewResponse": { "description": "What a patch review request produced.", "properties": { "existing": { "description": "True when this patch on this base already had a review and that one\n is returned. Sending the same patch twice reviews it once.", "type": "boolean" }, "patch_digest": { "description": "SHA-256 of the canonical patch, the identity the review pins with\n the repository and base commit.", "type": "string" }, "review_id": { "description": "The review of this patch on this base, readable through the review\n and findings routes.", "format": "uuid", "type": "string" } }, "required": [ "review_id", "existing", "patch_digest" ], "type": "object" }, "PermissionView": { "enum": [ "PERMIT", "BLOCK" ], "type": "string" }, "PlanProjection": { "properties": { "assessments": { "description": "Environment assessment bindings recorded in the plan.", "items": { "$ref": "#/components/schemas/AssessmentProjection" }, "type": "array" }, "base_sha": { "description": "Base commit pinned by the change digest.", "type": "string" }, "change_digest_sha256": { "description": "Digest of the exact retained change input.", "type": "string" }, "fallback_causes": { "description": "Safe codes for fallback causes. Unrecognized values are never echoed.", "items": { "type": "string" }, "type": "array" }, "files": { "description": "File routing facts recorded in the plan.", "items": { "$ref": "#/components/schemas/FileProjection" }, "type": "array" }, "head_sha": { "description": "Head commit pinned by the change digest.", "type": "string" }, "repository_id": { "description": "Repository named by the validated immutable plan.", "format": "uuid", "type": "string" } }, "required": [ "repository_id", "base_sha", "head_sha", "change_digest_sha256", "files", "assessments", "fallback_causes" ], "type": "object" }, "Problem": { "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "RFC 9457 problem-details body. `type` is omitted and therefore\n `about:blank`: the `title`/`detail` pair carries the meaning.", "properties": { "detail": { "description": "A caller-safe explanation of this occurrence, absent when the cause is an internal\n error that is logged rather than returned.", "type": [ "string", "null" ] }, "status": { "description": "The HTTP status code of the response that carries this body.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "title": { "description": "A short, stable summary of the problem class, such as `not found` or `conflict`.", "type": "string" } }, "required": [ "title", "status" ], "title": "Problem", "type": "object" }, "PullRequestMergeGate": { "properties": { "assessment_count": { "description": "The number of environment assessments counted by the recorded decision. Null before a decision.", "format": "int32", "type": [ "integer", "null" ] }, "blocking_severity": { "description": "The frozen blocking threshold, either SERIOUS or WARNING; later settings do not restamp it.", "type": "string" }, "bypassed_at": { "description": "When the bypass receipt was recorded. Null when this gate has no recorded bypass.", "format": "date-time", "type": [ "string", "null" ] }, "coverage_digest": { "description": "The digest of the deterministic coverage used by the decision, or null when no digest was recorded.", "type": [ "string", "null" ] }, "decided_at": { "description": "When the immutable decision was recorded. Null before a decision.", "format": "date-time", "type": [ "string", "null" ] }, "decision": { "anyOf": [ { "$ref": "#/components/schemas/Outcome" }, { "type": "null" } ], "description": "The immutable ALLOW or BLOCK decision. Null until a decision is recorded." }, "finding_count": { "description": "The number of blocking findings counted by the recorded decision. Null before a decision.", "format": "int32", "type": [ "integer", "null" ] }, "head_sha": { "description": "The exact lowercase commit SHA whose captured policy this gate evaluates.", "type": "string" }, "id": { "description": "The immutable identity of the gate captured for this tenant, repository and head.", "format": "uuid", "type": "string" }, "merge_commit_sha": { "description": "The exact merge commit reported by GitHub for the bypass, or null when none was reported.", "type": [ "string", "null" ] }, "merged_by_github_user_id": { "description": "The stable GitHub user ID reported by a merged-close bypass, or null when none was reported.", "format": "int64", "type": [ "integer", "null" ] }, "merged_pull_request_number": { "description": "The actual pull request merged in the recorded bypass, which may differ from the captured PR.", "format": "int64", "type": [ "integer", "null" ] }, "policy_version": { "description": "The deterministic policy version frozen when this gate was captured.", "type": "string" }, "pull_request_number": { "description": "The first pull request that captured this head's gate; a shared-head merge may name another PR.", "format": "int64", "type": "integer" }, "reason_code": { "description": "The recorded deterministic decision or refusal reason. Null until a decision is recorded.", "type": [ "string", "null" ] }, "review_id": { "description": "The first review captured for this gate. Null when its trigger was refused before a review existed.", "format": "uuid", "type": [ "string", "null" ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/GateStatus" } ], "description": "The current gate projection, including a recorded bypass or supersession by a newer head." } }, "required": [ "id", "pull_request_number", "head_sha", "status", "policy_version", "blocking_severity" ], "type": "object" }, "RefusedEnvironment": { "description": "An environment a refusal names. `external_key` is how its pages are\n addressed.", "properties": { "display_name": { "description": "The environment's display name. Tenant free text: render as text.", "type": "string" }, "external_key": { "description": "The environment's stable machine key, unique within the organization.", "type": "string" }, "id": { "description": "The environment's identifier.", "format": "uuid", "type": "string" }, "status": { "description": "The environment's lifecycle status, such as `READY`.", "type": "string" } }, "required": [ "id", "external_key", "display_name", "status" ], "type": "object" }, "RelatedReview": { "properties": { "created_at": { "description": "When the related review was created.", "format": "date-time", "type": "string" }, "head_commit_sha": { "description": "The head commit the related review is pinned to. Absent when it recorded none.", "type": [ "string", "null" ] }, "public_key": { "description": "The related review's stable public address.", "type": "string" }, "relation": { "description": "A direct lineage relation, or `EARLIER_RUN` / `LATER_RUN` when the two\n reviews share a pull request without a direct lineage edge.", "type": "string" }, "review_id": { "description": "The related review's identifier.", "format": "uuid", "type": "string" }, "run_number": { "description": "The related review's one-based ordinal within its pull request. Absent for a review that is not of a pull request.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "description": "The related review's lifecycle status.", "type": "string" } }, "required": [ "relation", "review_id", "public_key", "status", "created_at" ], "type": "object" }, "RepositoryGuidance": { "properties": { "additional_prompt": { "description": "The repository-specific reviewer guidance new reviews snapshot, null when none is set.", "type": [ "string", "null" ] }, "repository_id": { "description": "The repository's stable Proofline ID.", "format": "uuid", "type": "string" } }, "required": [ "repository_id" ], "type": "object" }, "RepositoryName": { "properties": { "full_name": { "description": "The provider's `owner/name`. Display metadata: it can change on a\n rename, so callers keep `id`.", "type": "string" }, "id": { "description": "The repository's stable Proofline ID.", "format": "uuid", "type": "string" } }, "required": [ "id", "full_name" ], "type": "object" }, "RepositoryNames": { "properties": { "repositories": { "description": "The organization's repositories that are not deleted, ordered by name; a\n repository-restricted token sees only its allowlist.", "items": { "$ref": "#/components/schemas/RepositoryName" }, "type": "array" } }, "required": [ "repositories" ], "type": "object" }, "RerunResponse": { "description": "Manual rerun: a new review of the same immutable subjects, under a fresh\n trigger key so history accumulates instead of overwriting.", "properties": { "public_key": { "description": "The new review's stable public address.", "type": "string" }, "pull_request_number": { "description": "The pull request number. Absent for a deployment review.", "format": "int64", "type": [ "integer", "null" ] }, "repository_name": { "description": "The repository's name within its owner. Absent when the original review names no repository.", "type": [ "string", "null" ] }, "review_id": { "description": "The new review's identifier.", "format": "uuid", "type": "string" }, "run_number": { "description": "The new review's one-based ordinal within its pull request. Absent for a deployment review.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "review_id", "public_key" ], "type": "object" }, "ReviewActions": { "properties": { "publish": { "description": "Whether the caller may publish this pull request review's withheld\n results, which requires a browser session and repository write access.", "type": "boolean" }, "rerun": { "description": "Whether the caller may rerun this review.", "type": "boolean" }, "stop": { "description": "Whether the caller may stop this review from a browser session.", "type": "boolean" }, "unavailable_reason": { "anyOf": [ { "$ref": "#/components/schemas/ActionUnavailability" }, { "type": "null" } ], "description": "Why an action is unavailable, when a permission or repository check\n denied it. Null when no check denied one, which does not mean every\n action is allowed." }, "validate_findings": { "description": "Whether the caller may record decisions on findings from a browser\n session.", "type": "boolean" } }, "required": [ "rerun", "publish", "stop", "validate_findings" ], "type": "object" }, "ReviewDiffStats": { "properties": { "additions": { "description": "Lines added across every changed file in the pinned comparison.", "format": "int64", "type": "integer" }, "deletions": { "description": "Lines deleted across every changed file in the pinned comparison.", "format": "int64", "type": "integer" } }, "required": [ "additions", "deletions" ], "type": "object" }, "ReviewFilters": { "properties": { "authors": { "description": "Authors of visible pull request reviews, one per GitHub user.", "items": { "$ref": "#/components/schemas/AuthorChoice" }, "type": "array" }, "environments": { "description": "Environments assessed by at least one visible review, ordered by\n display name.", "items": { "$ref": "#/components/schemas/FilterChoice" }, "type": "array" }, "repositories": { "description": "Repositories that have at least one visible review, ordered by full\n name.", "items": { "$ref": "#/components/schemas/FilterChoice" }, "type": "array" } }, "required": [ "repositories", "environments", "authors" ], "type": "object" }, "ReviewOpenItems": { "properties": { "accepted_risk_count": { "description": "Finding series whose current decision is an unexpired `ACCEPTED_RISK`.", "format": "uint64", "minimum": 0, "type": "integer" }, "current_head_provider_updated_at": { "description": "GitHub's update time for the recorded pull request state that\n `current_head_sha` comes from. Null when none is recorded.", "format": "date-time", "type": [ "string", "null" ] }, "current_head_sha": { "description": "The pull request's head commit as Proofline last recorded it from\n GitHub. Null when no pull request state is recorded.", "type": [ "string", "null" ] }, "environments": { "description": "This review's environment assessments that are not `COMPLETED`, ordered\n by environment key.", "items": { "$ref": "#/components/schemas/OpenItemEnvironment" }, "type": "array" }, "evaluated_scope_known": { "description": "Whether the review recorded at least one environment assessment. False\n means the evaluated scope is unknown, so an empty `environments` proves\n nothing.", "type": "boolean" }, "head_state": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsHeadState" } ], "description": "Whether `reviewed_head_sha` matches `current_head_sha`; `UNKNOWN` when\n either is missing." }, "is_latest_review": { "description": "Whether this review is the newest review of its pull request the caller\n can see.", "type": "boolean" }, "latest_review_head_sha": { "description": "The head commit of the newest review of this pull request the caller\n can see. Null when that review recorded none.", "type": [ "string", "null" ] }, "latest_review_head_state": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsHeadState" } ], "description": "Whether `latest_review_head_sha` matches `current_head_sha`; `UNKNOWN`\n when either is missing." }, "observed_at": { "description": "When the database facts in this observation were read, all from one\n statement.", "format": "date-time", "type": "string" }, "open_findings": { "allOf": [ { "$ref": "#/components/schemas/OpenFindingCounts" } ], "description": "Unresolved finding series that still demand attention, by severity:\n this review's own, and earlier published series of the pull request\n that this review did not find again." }, "review_status": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsReviewStatus" } ], "description": "This review's recorded status; `UNKNOWN` for a status this build does\n not recognize." }, "reviewed_head_sha": { "description": "The head commit this review evaluated. Null when the review recorded\n none.", "type": [ "string", "null" ] }, "threads": { "allOf": [ { "$ref": "#/components/schemas/OpenItemsThreads" } ], "description": "The count of unresolved Proofline review threads on GitHub, or why that\n count is unknown." } }, "required": [ "observed_at", "head_state", "latest_review_head_state", "is_latest_review", "review_status", "open_findings", "accepted_risk_count", "evaluated_scope_known", "environments", "threads" ], "type": "object" }, "ReviewPage": { "properties": { "filters": { "allOf": [ { "$ref": "#/components/schemas/ReviewFilters" } ], "description": "The values the review list can be filtered by, drawn from reviews the\n caller can see and independent of the current filters." }, "items": { "description": "The reviews on this page, newest first.", "items": { "$ref": "#/components/schemas/ReviewSummary" }, "type": "array" }, "next_cursor": { "description": "The cursor that requests the next page. Null when `truncated` is false.", "type": [ "string", "null" ] }, "truncated": { "description": "Whether more reviews match the query beyond this page.", "type": "boolean" } }, "required": [ "items", "truncated", "filters" ], "type": "object" }, "ReviewRoutingView": { "oneOf": [ { "description": "No immutable routing plan is retained for this review.", "properties": { "status": { "const": "NOT_RECORDED", "type": "string" } }, "required": [ "status" ], "type": "object" }, { "description": "A routing plan exists, but this server does not decode its version.", "properties": { "status": { "const": "UNSUPPORTED", "type": "string" }, "version": { "description": "Version identifier stored with the plan.", "type": "string" } }, "required": [ "status", "version" ], "type": "object" }, { "description": "Validated routing and placement facts for this review.", "properties": { "findings": { "description": "Recorded publication decisions, with unrecognized codes masked.", "items": { "$ref": "#/components/schemas/RoutingFindingView" }, "type": "array" }, "plan": { "allOf": [ { "$ref": "#/components/schemas/PlanProjection" } ], "description": "Safe routing projection bound to this review's retained inputs." }, "status": { "const": "SUPPORTED", "type": "string" }, "version": { "description": "Version of the validated routing plan.", "type": "string" } }, "required": [ "status", "version", "plan", "findings" ], "type": "object" } ] }, "ReviewSummary": { "properties": { "assessment_count": { "description": "How many environment assessments this review has.", "format": "int64", "type": "integer" }, "completed_at": { "description": "When the review reached a terminal status. Absent while it is still pending or running.", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the review was created.", "format": "date-time", "type": "string" }, "current_head_commit_sha": { "description": "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.", "type": [ "string", "null" ] }, "environment_display_names": { "description": "Display names of this review's assessed environments, not current repository links.", "items": { "type": "string" }, "type": "array" }, "finding_count": { "description": "How many findings this review's assessments recorded, across all of them.", "format": "int64", "type": "integer" }, "head_commit_sha": { "description": "The head commit this review is pinned to. For a patch review, the\n revision ID Proofline derives from its base commit and patch digest,\n which is not a commit. Absent when the review recorded none.", "type": [ "string", "null" ] }, "head_commit_url": { "description": "The exact revision reviewed. A commit URL, never a branch URL: the\n branch moves, the reviewed input does not. Absent for a patch review.", "type": [ "string", "null" ] }, "id": { "description": "The review's identifier.", "format": "uuid", "type": "string" }, "kind": { "description": "`PULL_REQUEST`, `DEPLOYMENT` or `PATCH`, a review of local changes\n sent as a patch.", "type": "string" }, "public_key": { "description": "The review's stable public address: `rev_` followed by its identifier without hyphens.", "type": "string" }, "publication": { "description": "Whether the review reached the pull request: `PUBLISHED`, `WITHHELD`,\n `PUBLICATION_REQUESTED` or `PUBLICATION_REFUSED`. A review run from\n Proofline is withheld until somebody publishes it.", "type": "string" }, "publication_detail": { "description": "Why a publication was refused, or how one failed. Server text.", "type": [ "string", "null" ] }, "pull_request_author_avatar_url": { "description": "Provider-supplied avatar URL. Login-derived `.png` URLs do not work for\n GitHub App bot accounts and are not portable across GitHub hosts.", "type": [ "string", "null" ] }, "pull_request_author_github_user_id": { "description": "The author's stable GitHub user id: identity for profile lookups,\n never display text. Absent when GitHub named no author.", "format": "int64", "type": [ "integer", "null" ] }, "pull_request_author_login": { "description": "Provider display metadata for the pull request author, not the rerun requester.", "type": [ "string", "null" ] }, "pull_request_author_url": { "description": "The author's profile on the deployment's GitHub host. Absent when no author login is known.", "type": [ "string", "null" ] }, "pull_request_number": { "description": "The pull request number. Absent for a deployment or patch review.", "format": "int64", "type": [ "integer", "null" ] }, "pull_request_state": { "description": "Current provider state of the pull request: `OPEN`, `CLOSED`, or\n `MERGED`. Absent for deployment reviews or a missing projection.", "type": [ "string", "null" ] }, "pull_request_title": { "description": "The pull request's title as provider state last reported it, so it\n names the change rather than only numbering it. Untrusted text:\n renderers must treat it as text, never markup.", "type": [ "string", "null" ] }, "pull_request_url": { "description": "The pull request on GitHub. Absent for a deployment review or when the repository is unknown.", "type": [ "string", "null" ] }, "repository_full_name": { "description": "The repository's `owner/name`. Absent when the review names no repository.", "type": [ "string", "null" ] }, "repository_id": { "description": "The review's repository. Set only on a single-review read, and absent there when the review names no repository.", "format": "uuid", "type": [ "string", "null" ] }, "repository_name": { "description": "The repository's name within its owner. Absent when the review names no repository.", "type": [ "string", "null" ] }, "repository_url": { "description": "The repository on GitHub. Absent when the deployment's web base\n cannot be joined with the stored name.", "type": [ "string", "null" ] }, "run_number": { "description": "One-based, append-only ordinal within one repository pull request.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "description": "The review's lifecycle status: `PENDING`, `RUNNING`, `COMPLETED`, `INCOMPLETE`, `FAILED`, `SUPERSEDED`, `STOPPED` or `EXCLUDED`.", "type": "string" }, "trigger_origin": { "description": "Who asked for this review: `AUTOMATIC`, `COMMAND`, `RERUN`, `MANUAL`,\n or `UNKNOWN` for a trigger key this build does not recognise.", "type": "string" } }, "required": [ "id", "public_key", "kind", "status", "assessment_count", "environment_display_names", "finding_count", "trigger_origin", "publication", "created_at" ], "type": "object" }, "ReviewedTreeCitationView": { "description": "One member of a review's declared tree that World cited.", "properties": { "content_sha256": { "description": "The member's content hash. Absent for a member a `REJECTED`\n population refused, because such a population keeps no members.", "type": [ "string", "null" ] }, "overlay_digest": { "description": "The overlay World read the member from.", "type": "string" }, "path": { "allOf": [ { "$ref": "#/components/schemas/UntrustedText" } ], "description": "The member's path in the repository at that revision. Repository\n text, so it can hold bidirectional controls that reorder what the\n reader sees." }, "population_kind": { "description": "The population the member belongs to, such as\n `WORKFLOW_DEFINITIONS`.", "type": "string" }, "role": { "description": "`PROPOSED_CODE_REVISION` (the reviewed commit) or\n `BASE_CODE_REVISION` (its merge base).", "type": "string" } }, "required": [ "role", "population_kind", "path", "overlay_digest" ], "type": "object" }, "ReviewsExportRow": { "description": "The NDJSON row and CSV column contract. Repository names are display data;\n the stable repository ID and recorded commit identify the reviewed input.", "properties": { "base_commit_sha": { "description": "The pinned base commit SHA, null when the review records none.", "type": [ "string", "null" ] }, "completed_at": { "description": "When the review finished, null while it has not.", "format": "date-time", "type": [ "string", "null" ] }, "created_at": { "description": "When the review was created; the export window filters on this time.", "format": "date-time", "type": "string" }, "dataset_version": { "description": "The row contract version, always `1`.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "github_repository_id": { "description": "GitHub's ID for the repository, null when the organization no longer owns it or the\n review records no repository.", "format": "int64", "type": [ "integer", "null" ] }, "head_commit_sha": { "description": "The pinned head commit SHA, null when the review records none.", "type": [ "string", "null" ] }, "kind": { "allOf": [ { "$ref": "#/components/schemas/ExportReviewKind" } ], "description": "Whether the review analyzes a pull request, a deployment or a local patch." }, "organization_id": { "description": "The organization that owns the review.", "format": "uuid", "type": "string" }, "pull_request_number": { "description": "The pull request number, null when the review records none, as for a deployment.", "format": "int64", "type": [ "integer", "null" ] }, "repository_full_name": { "description": "The repository's current `owner/name` display name, null when the organization no\n longer owns it or the review records no repository.", "type": [ "string", "null" ] }, "repository_id": { "description": "The stable ID of the review's primary repository, null when the review records none.", "format": "uuid", "type": [ "string", "null" ] }, "review_id": { "description": "The review's stable ID.", "format": "uuid", "type": "string" }, "run_number": { "description": "The review's ordinal among the reviews of its pull request, null for a review without\n a repository and pull request.", "format": "int64", "type": [ "integer", "null" ] }, "status": { "allOf": [ { "$ref": "#/components/schemas/ExportReviewStatus" } ], "description": "The review's recorded status." }, "trigger_origin": { "description": "What started the review, derived from its trigger key: `AUTOMATIC`, `COMMAND`,\n `RERUN`, `MANUAL`, or `UNKNOWN` for a key this build does not recognize.", "type": "string" } }, "required": [ "dataset_version", "organization_id", "review_id", "kind", "status", "trigger_origin", "created_at" ], "type": "object" }, "ReviewsMetadataStream": { "description": "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": { "properties": { "fallback_cause": { "description": "Recognized safe fallback cause, when present.", "type": [ "string", "null" ] }, "finding_id": { "description": "Finding whose retained placement is reported.", "format": "uuid", "type": "string" }, "floor_reason": { "description": "Recognized safe floor reason, when present.", "type": [ "string", "null" ] }, "placement": { "description": "Publication channel recorded for this finding.", "type": "string" }, "reason_codes": { "description": "Recognized safe reason codes; unknown values are represented as `UNRECOGNIZED`.", "items": { "type": "string" }, "type": "array" }, "rule": { "description": "Rule that produced the recorded placement.", "type": "string" } }, "required": [ "finding_id", "placement", "rule", "reason_codes" ], "type": "object" }, "RunNowMode": { "description": "Whether an explicit request may reuse a settled review of the live head.", "enum": [ "EXISTING_OR_NEW", "FULL" ], "type": "string" }, "RunNowRefusalView": { "description": "Why a run-now request created nothing, each reason with what the page\n needs to link the setting to change.", "oneOf": [ { "description": "The organization's trigger mode excludes pull requests: review\n settings.", "properties": { "reason": { "const": "TRIGGER_DISABLED", "type": "string" } }, "required": [ "reason" ], "type": "object" }, { "description": "Reviewing is off for this repository: the repository's review\n settings.", "properties": { "reason": { "const": "REPOSITORY_DISABLED", "type": "string" } }, "required": [ "reason" ], "type": "object" }, { "description": "No environment links this repository: the repository's setup.", "properties": { "reason": { "const": "NO_LINKED_ENVIRONMENT", "type": "string" } }, "required": [ "reason" ], "type": "object" }, { "description": "The environment is linked but the link has pull request reviews off:\n the repository's review settings, where environments are chosen.", "properties": { "environment": { "$ref": "#/components/schemas/RefusedEnvironment" }, "reason": { "const": "ENVIRONMENT_REVIEWS_OFF", "type": "string" } }, "required": [ "reason", "environment" ], "type": "object" }, { "description": "The environment reviews this repository but is not ready; its own\n account of why, when it has one, is `status_detail`. The\n environment's setup.", "properties": { "environment": { "$ref": "#/components/schemas/RefusedEnvironment" }, "reason": { "const": "ENVIRONMENT_NOT_READY", "type": "string" }, "status_detail": { "type": [ "string", "null" ] } }, "required": [ "reason", "environment" ], "type": "object" }, { "description": "The environment is ready and reviews this repository, but no cloud\n connection of its can currently supply evidence: the account is not\n connected, or the connection was revoked or predates the current\n permission manifest. Which one is on the environment's setup.", "properties": { "environment": { "$ref": "#/components/schemas/RefusedEnvironment" }, "reason": { "const": "ENVIRONMENT_EVIDENCE_UNAVAILABLE", "type": "string" } }, "required": [ "reason", "environment" ], "type": "object" }, { "description": "The environment's active typed revision cannot name one delivery\n target for this repository. The environment's link to the\n repository; absent only if the environment was removed meanwhile.", "properties": { "detail": { "type": "string" }, "environment": { "anyOf": [ { "$ref": "#/components/schemas/RefusedEnvironment" }, { "type": "null" } ] }, "reason": { "const": "INVALID_DELIVERY_CONFIGURATION", "type": "string" } }, "required": [ "reason", "detail" ], "type": "object" }, { "description": "Proofline has not received this pull request from GitHub: the GitHub\n installation.", "properties": { "reason": { "const": "PULL_REQUEST_UNKNOWN", "type": "string" } }, "required": [ "reason" ], "type": "object" }, { "description": "The pull request's author holds no seat: seat settings.", "properties": { "reason": { "const": "AUTHOR_HAS_NO_SEAT", "type": "string" } }, "required": [ "reason" ], "type": "object" }, { "description": "The pull request closed between GitHub's answer that it was open and\n the review's creation. Nothing to change; the pull request itself.", "properties": { "reason": { "const": "PULL_REQUEST_CLOSED", "type": "string" } }, "required": [ "reason" ], "type": "object" } ] }, "RunNowRefused": { "description": "A run-now request that created nothing, as the 400 it is answered with.\n\n The refusal is a configuration fact, not a failure, and it is still sent\n as an RFC 9457 problem: `title`, `status` and `detail` are what a client\n that knows only problems shows, and `repository_name` and `refusal` are\n the extension members a client that knows refusals links from. During a\n rollout a page loaded from the previous bundle keeps working against\n this server, because a refusal was a 400 with a `detail` before too.", "properties": { "detail": { "description": "One sentence naming the condition and the setting to change, for a\n reader with no link to follow.", "type": "string" }, "refusal": { "allOf": [ { "$ref": "#/components/schemas/RunNowRefusalView" } ], "description": "Why nothing was created, with what the page needs to link the setting to change." }, "repository_name": { "description": "The repository's name within its owner, as its pages are addressed.", "type": "string" }, "status": { "description": "Always 400.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "title": { "description": "Always `invalid request`.", "type": "string" } }, "required": [ "title", "status", "detail", "repository_name", "refusal" ], "type": "object" }, "RunNowRequest": { "additionalProperties": false, "description": "An empty body keeps the run-now behavior existing clients request.", "properties": { "mode": { "allOf": [ { "$ref": "#/components/schemas/RunNowMode" } ], "description": "`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." } }, "type": "object" }, "RunNowResponse": { "description": "What a run-now request produced: a review of the live head, created by\n this request or found already owning the head.", "properties": { "automatic_reviews_paused": { "description": "True when automatic reviews are stopped on this pull request. The\n review ran anyway; the flag is why the page can say so.", "type": "boolean" }, "existing": { "description": "True when this head already carried a review and that one is\n returned. Clicking twice does not run twice.", "type": "boolean" }, "review_id": { "description": "The review that owns the live head, new or existing.", "format": "uuid", "type": "string" }, "run_number": { "description": "The review's one-based ordinal within its pull request, which\n completes the run's console address.", "format": "int64", "type": "integer" } }, "required": [ "review_id", "run_number", "existing", "automatic_reviews_paused" ], "type": "object" }, "SpendAccountKind": { "enum": [ "DEPLOYMENT", "TENANT_CREDENTIAL", "UNATTRIBUTED" ], "type": "string" }, "SpendExportRow": { "description": "UTC daily debit totals using only the account and transport recorded at charge time.", "properties": { "account": { "description": "Recorded attribution, not a current credential label or inferred account.", "type": [ "string", "null" ] }, "account_kind": { "allOf": [ { "$ref": "#/components/schemas/SpendAccountKind" } ], "description": "The account kind recorded at charge time, `UNATTRIBUTED` when the debit records none." }, "dataset_version": { "description": "The row contract version, always `1`.", "format": "uint16", "maximum": 65535, "minimum": 0, "type": "integer" }, "day": { "description": "UTC midnight. The requested window can cover only part of this day.", "format": "date-time", "type": "string" }, "debits": { "description": "The number of debits summed into this row.", "format": "int64", "type": "integer" }, "microcredits": { "description": "Exact integer charge units; one credit contains one million microcredits.", "format": "int64", "type": "integer" }, "organization_id": { "description": "The organization charged.", "format": "uuid", "type": "string" }, "transport": { "description": "The model transport recorded at charge time, null when the debit records none.", "type": [ "string", "null" ] } }, "required": [ "dataset_version", "organization_id", "day", "account_kind", "microcredits", "debits" ], "type": "object" }, "SubjectAuthorization": { "description": "One assessment's authorization of one subject, by identity.\n\n The display name is not the answer on its own: an environment's external key\n is unique within its organization and a display name is mutable metadata,\n so two environments of one review can carry the same one.\n Collapsing to it would leave a reader unable to tell which assessment\n authorized the subject and which one gapped, which is the confusion this\n field exists to remove.", "properties": { "assessment_id": { "description": "The assessment this authorization belongs to, as `AssessmentView.id`\n names it. A reader joins on this, never on the display name.", "format": "uuid", "type": "string" }, "environment_display_name": { "description": "What a reader recognizes the environment by. Display metadata, and\n tenant free text: a consumer contains it before rendering.", "type": "string" }, "environment_external_key": { "description": "The environment's stable machine key, unique within the organization.", "type": "string" }, "environment_id": { "description": "The environment the authorizing assessment belongs to.", "format": "uuid", "type": "string" } }, "required": [ "assessment_id", "environment_id", "environment_external_key", "environment_display_name" ], "type": "object" }, "SubjectView": { "properties": { "artifact_digest": { "description": "An immutable OCI digest, never a mutable tag.", "type": [ "string", "null" ] }, "commit_sha": { "description": "The pinned commit of a `GIT_REVISION` subject, or the base commit a\n `GIT_PATCH` subject applies to. Absent for other kinds.", "type": [ "string", "null" ] }, "deployment_external_id": { "description": "The GitHub deployment identifier a `GITHUB_WORKFLOW_RUN` subject ran for. Absent when the run was not for a deployment.", "type": [ "string", "null" ] }, "id": { "description": "The subject's stable identifier. It holds across a poll refresh even\n when a concurrently populated subject shifts this response's\n `(kind, id)` order: a client keying its own local UI state (an open\n disclosure, a focused control) by array index would otherwise lose\n that state to a reorder that changed nothing it owns.", "format": "uuid", "type": "string" }, "kind": { "description": "`GIT_REVISION`, `GIT_PATCH`, `GITHUB_WORKFLOW_RUN`, `ARTIFACT` or `DEPLOYMENT`.", "type": "string" }, "patch_digest": { "description": "The SHA-256 of a `GIT_PATCH` subject's canonical patch. Absent for\n other kinds.", "type": [ "string", "null" ] }, "release_authorizations": { "description": "The assessments whose own verified release set authorized this\n subject.\n\n A review with several environments accumulates one subject list, but\n authorization is per assessment: an artifact one environment's read\n authenticated is not evidence for a neighbour whose own read gapped or\n refused. Naming the assessments keeps the union from reading as a\n shared fact.\n\n Empty for a subject no release-set read produced (the reviewed\n revision, the workflow run, a deployment), because those are the\n review's own coordinates rather than one environment's authenticated\n evidence, not because every environment refused them.", "items": { "$ref": "#/components/schemas/SubjectAuthorization" }, "type": "array" }, "repository_full_name": { "description": "Absent only when the subject's repository record itself is gone.", "type": [ "string", "null" ] }, "repository_id": { "description": "The immutable repository identity of this subject, including companions.", "format": "uuid", "type": [ "string", "null" ] }, "role": { "description": "`PRIMARY` for the revision under review; `COMPANION` for context read\n from another authenticated repository.", "type": "string" }, "url": { "description": "The subject on GitHub: the commit for a revision, the run for a\n workflow run. Absent for kinds GitHub does not address (`GIT_PATCH`,\n ARTIFACT, DEPLOYMENT) or when the subject's repository is unknown.", "type": [ "string", "null" ] }, "workflow_attempt": { "description": "The attempt number of a `GITHUB_WORKFLOW_RUN` subject. Absent for other kinds.", "format": "int32", "type": [ "integer", "null" ] }, "workflow_run_id": { "description": "The GitHub Actions run of a `GITHUB_WORKFLOW_RUN` subject. Absent for other kinds.", "format": "int64", "type": [ "integer", "null" ] } }, "required": [ "id", "kind", "role", "release_authorizations" ], "type": "object" }, "ThreadObservationFreshness": { "enum": [ "FRESH", "STALE" ], "type": "string" }, "ThreadObservationView": { "description": "A read of GitHub's thread state. `observed_at` is when Proofline read it.", "properties": { "freshness": { "allOf": [ { "$ref": "#/components/schemas/ThreadObservationFreshness" } ], "description": "`STALE` when the pull request is open and this observation is more than 24 hours old, otherwise `FRESH`." }, "github_comment_url": { "description": "The finding's root comment on GitHub. Absent when the repository is unknown.", "type": [ "string", "null" ] }, "observed_at": { "description": "When Proofline read the thread state from GitHub.", "format": "date-time", "type": "string" }, "provider_state": { "anyOf": [ { "$ref": "#/components/schemas/ThreadProviderState" }, { "type": "null" } ], "description": "Absent only when the provider read failed before GitHub returned state." }, "reply_evidence": { "allOf": [ { "$ref": "#/components/schemas/ThreadReplyEvidence" } ], "description": "`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": { "description": "The stable GitHub identity of whoever resolved the thread. Absent when GitHub named no resolver.", "format": "int64", "type": [ "integer", "null" ] }, "resolver_login": { "description": "The login of whoever resolved the thread, as GitHub reported it. Provider text, and absent when GitHub named no resolver.", "type": [ "string", "null" ] } }, "required": [ "reply_evidence", "observed_at", "freshness" ], "type": "object" }, "ThreadProviderState": { "enum": [ "OPEN", "RESOLVED" ], "type": "string" }, "ThreadReplyEvidence": { "enum": [ "RECORDED", "NONE_CONFIRMED", "INCOMPLETE" ], "type": "string" }, "UnresolvedReason": { "description": "World's reason an executed check did not settle. A gate weighs the three\n alike, and each asks the reader for a different response.", "oneOf": [ { "const": "NEEDS_EVIDENCE", "description": "The evidence World held neither established nor refuted the property.", "type": "string" }, { "const": "UNSUPPORTED", "description": "The case is outside what the check can decide. More evidence does not\n change the answer.", "type": "string" }, { "const": "REGENERATE_SCENARIO", "description": "The scenario the check ran against had to be declared again before\n its answer meant anything. A new review declares it again.", "type": "string" } ] }, "UntrustedText": { "description": "Text that came out of the reviewer model, or out of a repository the model\n read. It is data, never markup, never a URL, never an instruction.\n\n The wrapper exists so the untrustedness cannot be lost on the way to a\n renderer: there is no field on a turn that carries this text under a name a\n client could mistake for something safe, and unwrapping it is a deliberate\n act in the client's own code.", "properties": { "untrusted_text": { "description": "The text itself. Render it as plain text only.", "type": "string" } }, "required": [ "untrusted_text" ], "type": "object" } }, "securitySchemes": { "bearerAuth": { "bearerFormat": "Proofline scoped token", "description": "One organization and named review scopes; browser administrative actions reject tokens", "scheme": "bearer", "type": "http" } } }, "info": { "title": "Proofline Review API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/api/v1/organizations/{org_id}/exports/{dataset}": { "get": { "description": "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.", "operationId": "export_reviews", "parameters": [ { "in": "path", "name": "dataset", "required": true, "schema": { "$ref": "#/components/schemas/Dataset" }, "style": "simple" }, { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "description": "Treat this signed continuation as opaque. Retain the same window and grouping.", "in": "query", "name": "cursor", "schema": { "description": "Treat this signed continuation as opaque. Retain the same window and grouping.", "type": [ "string", "null" ] }, "style": "form" }, { "description": "ndjson (default) or csv. Each CSV page repeats its column header.", "in": "query", "name": "format", "schema": { "description": "ndjson (default) or csv. Each CSV page repeats its column header.", "type": [ "string", "null" ] }, "style": "form" }, { "description": "Inclusive RFC3339 creation, debit or first-publication time. At most 31 days.", "in": "query", "name": "from", "required": true, "schema": { "description": "Inclusive RFC3339 creation, debit or first-publication time. At most 31 days.", "type": "string" }, "style": "form" }, { "description": "`finding_outcomes` only; defaults to repository.", "in": "query", "name": "group_by", "schema": { "anyOf": [ { "$ref": "#/components/schemas/FindingOutcomesGroupBy" }, { "type": "null" } ], "description": "`finding_outcomes` only; defaults to repository." }, "style": "form" }, { "description": "Exclusive RFC3339 creation, debit or first-publication time.", "in": "query", "name": "to", "required": true, "schema": { "description": "Exclusive RFC3339 creation, debit or first-publication time.", "type": "string" }, "style": "form" } ], "responses": { "200": { "content": { "application/x-ndjson": { "schema": { "$ref": "#/components/schemas/ReviewsMetadataStream" }, "x-proofline-row-schema": { "$ref": "#/components/schemas/ExportRow" } }, "text/csv": { "schema": { "$ref": "#/components/schemas/ReviewsMetadataStream" }, "x-proofline-row-schema": { "$ref": "#/components/schemas/ExportRow" } } }, "description": "At most 5000 review, finding, validation or daily spend rows, or 1000 finding-outcome groups. NDJSON uses the declared dataset row per line; CSV uses the same named columns, RFC4180 quoting and formula-safe text. Nested count and reference objects are JSON text in CSV cells. The settled horizon and optional opaque continuation are response headers.", "headers": { "X-Proofline-Export-Next-Cursor": { "description": "Opaque signed continuation. Absent on the last page.", "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "string", "type": "string" }, "style": "simple" }, "X-Proofline-Export-Settled-Until": { "description": "Frozen RFC3339 horizon, five minutes before the first request.", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "string", "type": "string" }, "style": "simple" }, "X-Proofline-Export-Version": { "description": "Dataset version 1.", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "title": "string", "type": "string" }, "style": "simple" } } }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Export review metadata", "x-proofline-token-scope": "analytics:read" } }, "/api/v1/organizations/{org_id}/findings/{finding_id}": { "get": { "description": "Returns one finding with its evidence references, validation state and causal graph.", "operationId": "get_finding", "parameters": [ { "in": "path", "name": "finding_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFinding" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a finding", "x-proofline-token-scope": "findings:read" } }, "/api/v1/organizations/{org_id}/repositories/{repo_id}/patch-reviews": { "post": { "description": "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.", "operationId": "request_patch_review", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "repo_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchReviewRequest" } } }, "description": "Local changes to review: a unified diff against a commit GitHub has.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PatchReviewResponse" } } }, "description": "What a patch review request produced." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNowRefused" } } }, "description": "A run-now request that created nothing, as the 400 it is answered with.\n\n The refusal is a configuration fact, not a failure, and it is still sent\n as an RFC 9457 problem: `title`, `status` and `detail` are what a client\n that knows only problems shows, and `repository_name` and `refusal` are\n the extension members a client that knows refusals links from. During a\n rollout a page loaded from the previous bundle keeps working against\n this server, because a refusal was a 400 with a `detail` before too." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Review local changes", "x-proofline-token-scope": "reviews:request" } }, "/api/v1/organizations/{org_id}/repositories/{repo_id}/pull-requests/{number}/review": { "post": { "description": "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.", "operationId": "request_review", "parameters": [ { "in": "path", "name": "number", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "simple" }, { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "repo_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNowRequest" } } }, "description": "An empty body keeps the run-now behavior existing clients request." }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNowResponse" } } }, "description": "What a run-now request produced: a review of the live head, created by\n this request or found already owning the head." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunNowRefused" } } }, "description": "A run-now request that created nothing, as the 400 it is answered with.\n\n The refusal is a configuration fact, not a failure, and it is still sent\n as an RFC 9457 problem: `title`, `status` and `detail` are what a client\n that knows only problems shows, and `repository_name` and `refusal` are\n the extension members a client that knows refusals links from. During a\n rollout a page loaded from the previous bundle keeps working against\n this server, because a refusal was a 400 with a `detail` before too." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Request a pull request review", "x-proofline-token-scope": "reviews:request" } }, "/api/v1/organizations/{org_id}/repositories/{repo_id}/review-guidance": { "get": { "description": "Returns the review guidance configured for a repository, for tools and coding agents that read it before writing code.", "operationId": "get_review_guidance", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "repo_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryGuidance" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get repository review guidance", "x-proofline-token-scope": "guidance:read" } }, "/api/v1/organizations/{org_id}/repository-names": { "get": { "description": "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.", "operationId": "list_repositories", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "format": "uuid", "title": "Uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RepositoryNames" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "List repository names", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews": { "get": { "description": "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.", "operationId": "list_reviews", "parameters": [ { "description": "`needed` lists terminal reviews of open pull requests with active\n findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit.", "in": "query", "name": "attention", "schema": { "description": "`needed` lists terminal reviews of open pull requests with active\n findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "author", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "environment", "schema": { "format": "uuid", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "findings", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "kind", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "format": "int64", "type": [ "integer", "null" ] }, "style": "form" }, { "in": "query", "name": "repository", "schema": { "format": "uuid", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "search", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "status", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "path", "name": "org_id", "required": true, "schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "format": "uuid", "title": "Uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewPage" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "List reviews", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews/deployments/{public_key}": { "get": { "description": "Returns the deployment review with the given public key.", "operationId": "get_deployment_review", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "public_key", "required": true, "schema": { "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReviewDetail" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a deployment review", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews/pr/{repository}/{pull_request_number}": { "get": { "description": "Lists the review runs of one pull request, addressed by repository name and pull request number.", "operationId": "list_pull_request_reviews", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "pull_request_number", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "simple" }, { "in": "path", "name": "repository", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "description": "`needed` lists terminal reviews of open pull requests with active\n findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit.", "in": "query", "name": "attention", "schema": { "description": "`needed` lists terminal reviews of open pull requests with active\n findings, FAILED/INCOMPLETE/STOPPED execution, or an earlier reviewed commit.", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "author", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "cursor", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "environment", "schema": { "format": "uuid", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "findings", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "kind", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "limit", "schema": { "format": "int64", "type": [ "integer", "null" ] }, "style": "form" }, { "in": "query", "name": "repository", "schema": { "format": "uuid", "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "search", "schema": { "type": [ "string", "null" ] }, "style": "form" }, { "in": "query", "name": "status", "schema": { "type": [ "string", "null" ] }, "style": "form" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewPage" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "List a pull request's review runs", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews/pr/{repository}/{pull_request_number}/runs/{run_number}": { "get": { "description": "Returns one review run of a pull request, addressed by repository name, pull request number and run number.", "operationId": "get_pull_request_review", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "pull_request_number", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "simple" }, { "in": "path", "name": "repository", "required": true, "schema": { "type": "string" }, "style": "simple" }, { "in": "path", "name": "run_number", "required": true, "schema": { "format": "int64", "type": "integer" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReviewDetail" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a pull request review run", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews/{review_id}": { "get": { "description": "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.", "operationId": "get_review", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "review_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerReviewDetail" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get a review", "x-proofline-token-scope": "reviews:read" } }, "/api/v1/organizations/{org_id}/reviews/{review_id}/assessments/{assessment_id}": { "get": { "description": "Returns one assessment of a review with its decision, checks and findings.", "operationId": "get_assessment", "parameters": [ { "in": "path", "name": "assessment_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "review_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerAssessmentDetail" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get an assessment", "x-proofline-token-scope": "findings:read" } }, "/api/v1/organizations/{org_id}/reviews/{review_id}/rerun": { "post": { "description": "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.", "operationId": "rerun_review", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "review_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RerunResponse" } } }, "description": "Manual rerun: a new review of the same immutable subjects, under a fresh\n trigger key so history accumulates instead of overwriting." }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Rerun a review", "x-proofline-token-scope": "reviews:rerun" } }, "/api/v1/organizations/{org_id}/reviews/{review_id}/routing": { "get": { "description": "Returns the review's validated routing plan and recorded finding placements. It reports retained routing facts, not model output or a deployment recommendation.", "operationId": "get_review_routing", "parameters": [ { "in": "path", "name": "org_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" }, { "in": "path", "name": "review_id", "required": true, "schema": { "format": "uuid", "type": "string" }, "style": "simple" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReviewRoutingView" } } }, "description": "" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "An RFC 9457 problem; the HTTP status remains authoritative." } }, "security": [ { "bearerAuth": [] } ], "summary": "Get review routing", "x-proofline-token-scope": "reviews:read" } } } }