---
title: "Session: propose a structured PM amendment against the exact current repository-body revision without mutating intent.md. API key: record an agent PROPOSAL against a recorded implementation finding; it is stored as a change request the repository agent cannot consume or apply until a signed-in writer accepts it, and one origin=agent evidence row is written and anchored to the target claim."
method: POST
path: "/api/v1/intents/{id}/change-requests"
tags: ["change requests"]
---

# Session: propose a structured PM amendment against the exact current repository-body revision without mutating intent.md. API key: record an agent PROPOSAL against a recorded implementation finding; it is stored as a change request the repository agent cannot consume or apply until a signed-in writer accepts it, and one origin=agent evidence row is written and anchored to the target claim.

`POST /api/v1/intents/{id}/change-requests`

Creation runs under the intent row lock and validates the expected value against the immutable base snapshot for both principals. It inserts only intent_change_requests (plus, for agent proposals, one evidence_items row, an additive evidence anchor and, when the finding is recorded inline, the finding itself, all in the same transaction); the repo-owned intent body is never edited. sourceUrl must be http(s). Consumable = status open AND (authorPrincipal session OR accepted). Plan: .claude/plans/agent-proposed-corrections.md.

## Path parameters

- `id` string, required

## Request body

- object
  - `findingId` string — Agent proposals only: id of the implementation finding this proposal answers (required unless finding is given).
  - `finding` object — Agent proposals only: record the finding inline, { assumption, finding, target?, source? }.
  - `sourceUrl` string — Agent proposals only: PR or commit link stored on the evidence row.
  - `supersedesRequestId` string — Session only (counter-proposal): the open request this one replaces; it becomes superseded in the same transaction.
  - `baseRepoBodyRevision` string, required — Exact 64-character revision shown to the PM. A stale base returns 409; it is never silently rebased.
  - `targetField` string, required — Semantic field or collection: title, severity, objective, currentState, outcomes, scope.inScope, scope.outOfScope, constraints, healthMetrics, edgeCases, decisions, verification, or implementationContext.
  - `targetItemId` string — Stable item id for outcome/verification items when one exists. Index-only targeting is forbidden.
  - `expectedOldValue` string — Required for replace/remove when no stable item id exists; compared to the immutable base snapshot.
  - `operation` string, required — replace, add, or remove. Scalar fields support replace only.
  - `proposedValue` string — Required for add/replace; forbidden for remove.
  - `reason` string, required — Why the product judgment requires this change (max 4000 chars).

## Response `201`

Request stored against the exact base revision

- object

## Other responses

- `400` — Invalid structured operation/value, or FINDING_REQUIRED (an API key proposed without findingId or finding)
- `401` — Missing or invalid API key/session
- `403` — Writer permission missing, or an API key attempted a counter-proposal (SESSION_REQUIRED)
- `404` — FINDING_NOT_FOUND: findingId is not on this intent
- `409` — Base revision or expected old value moved, or the counter-proposal target is no longer open
- `422` — The intent is not repository-authority
- `500` — DB error creating the request
- `503` — SCHEMA_MIGRATION_PENDING: the change-request functions in the database are out of date

## Changes

- **2026-09-04** `35441fda7ae7` — 7 info
  - the endpoint scheme security `bearerAuth` was added to the API
  - added the new optional request property `finding`
  - added the new optional request property `findingId`
  - added the new optional request property `sourceUrl`
  - …3 more
- **2026-09-01** `a660c0d36148` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/pathmode/apis/pathmode-api/changes/api/v1/intents/:id/change-requests/post.md)

---

[API](https://skmtc.dev/pathmode/apis/pathmode-api.md) · [All operations](https://skmtc.dev/pathmode/apis/pathmode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pathmode/apis/pathmode-api/revisions/0f4a7b92b504?raw)