---
title: "Grade an implementation against the intent spec by reading the pull request. With prUrl, Pathmode fetches the PR's changed files from GitHub and grades each outcome, constraint, constitution rule, edge case and verification check against the diff. Without it, the run is graded on the caller's own description and reported as basis 'self_report'. Stores the result on the intent and logs a verification_checkpoint implementation note."
method: POST
path: "/api/v1/intents/{id}/verify"
tags: ["intents"]
---

# Grade an implementation against the intent spec by reading the pull request. With prUrl, Pathmode fetches the PR's changed files from GitHub and grades each outcome, constraint, constitution rule, edge case and verification check against the diff. Without it, the run is graded on the caller's own description and reported as basis 'self_report'. Stores the result on the intent and logs a verification_checkpoint implementation note.

`POST /api/v1/intents/{id}/verify`

category enum is outcome|constraint|constitution|edge_case|verification; status enum is pass|fail|unclear|not_applicable. not_applicable means the change does not touch what the item governs; such items leave both the score and the pass decision entirely, so a workspace's standing constitution rules only count against changes that engage them. Outcomes are never not_applicable (coerced to unclear): an outcome the change does not reach is one not achieved yet. A run where every item was inapplicable fails, since engaging nothing verifies nothing. basis is 'artifact' when a pull request diff was read and 'self_report' when it was not; artifact records what was actually read (repo, prNumber, headSha, filesRead, filesOmitted, truncated) or why nothing was, via artifact.reason (no_pointer|not_connected|permission_denied|not_found|repo_not_installed|fetch_failed). prUrl must name a repository the workspace's GitHub installation actually covers: a GitHub App installation token can read any public repository, so readability alone is not provenance, and a PR from an unconnected repo degrades to self_report with reason repo_not_installed rather than being graded as evidence. Each result item carries basis ('artifact' = it cites the diff, 'self_report' = the run had no diff, 'none' = a diff existed but this verdict points at nothing in it) and evidence (validated citations: a cited path must be a file the grader was shown or it is discarded, and a cited hunk must appear in that file's patch or it is dropped while the path survives). On a diff-graded run, a pass with no valid citation is downgraded to unclear with basis 'none' BEFORE pass/score are computed, so an unbacked green feeds the outcome rule and the non-negotiable blocking like any other unclear. Uncited fails are not downgraded: weakening the strict direction would make missing citations lenient. A prUrl that cannot be read degrades the run to self_report rather than failing it, because acceptance of the GitHub App's pull_requests permission is per installation. Diffs are budgeted: files are ranked against the spec's wording and patches are included up to 60000 characters, with the remainder counted in filesOmitted and flagged by truncated. pass and score are computed server-side from the per-item statuses, not returned by the model. A run passes only when three things hold: no item failed; no constraint or constitution item is unclear, since an unconfirmed non-negotiable is not a pass; and at least one outcome item passed, since a verdict that cannot point to a single achieved outcome has established nothing. The outcome rule applies only when the spec states outcomes. Otherwise outcomes stay forgiving: unclear on an outcome, edge_case or verification item lowers the score without failing the run, so a spec with several outcomes passes on one confirmed. score is 0-100 with pass=1, unclear=0.5, fail=0 credit per item; a run with no items scores 0 and does not pass. Side effects: writes verification_result + updated_at on intent_specs, and inserts an intent_implementation_notes row with source 'verification_checkpoint'. Rate limited on the 'ai' bucket and counted against the workspace ai_conversations quota (403 when the monthly allowance is spent).

## Path parameters

- `id` string, required

## Request body

- object
  - `prUrl` string — Pull request URL (https://github.com/owner/repo/pull/123, the api.github.com equivalent, or the owner/repo#123 shorthand). Preferred input: Pathmode reads the diff from GitHub, so the evidence is not authored by the party being graded. Requires an active GitHub connection whose installation has accepted pull_requests:read.
  - `summary` string — What was implemented and how. Context for the grader, not evidence. Required only when prUrl is absent. At least one of prUrl or summary must be present.
  - `codeChanges` string — Deprecated, superseded by prUrl. Used as the description when no summary is given. A diff supplied by the caller about its own work is not independent evidence.

## Response `200`

Verification graded; returns the VerificationResult object

- object

## Other responses

- `400` — Invalid request body (zod) — e.g. missing/empty summary
- `401` — Missing/invalid API key or session
- `403` — Authenticated but lacks write scope, or the workspace's monthly AI conversation limit is reached
- `404` — Intent not found in this workspace
- `429` — Rate limited ('ai' bucket)
- `500` — Internal server error
- `503` — AI verification service temporarily unavailable (Gemini API error / 429 / 503)

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pathmode/pathmode-api/revisions/e419abb0a327/schema)