---
title: "Update intent content fields (title, objective, outcomes, constraints, etc.). Does NOT change status — use the /status endpoint."
method: PATCH
path: "/api/v1/intents/{id}"
tags: ["intents"]
---

# Update intent content fields (title, objective, outcomes, constraints, etc.). Does NOT change status — use the /status endpoint.

`PATCH /api/v1/intents/{id}`

Content-only update; status/shipped_at/verified_at are NOT touched here. Always sets updated_at. Requires at least one updatable field (otherwise 400). When edgeCases is provided, the prior intent state is snapshotted first so a failed edge-case sync can roll back. Response is re-fetched with INTENT_WITH_RELATIONS_SELECT so edgeCases/evidenceIds/relations are fully populated. No rate limiting on this PATCH.

## Path parameters

- `id` string, required

## Query parameters

- `workspace_id` string

## Request body

- object
  - `expectedVersion` string — The specVersion this edit was based on, from a previous read. When supplied and no longer current, the update is refused with 409 and code VERSION_CONFLICT rather than silently overwriting whoever moved it. Opaque: carry it, do not compute or compare it — the value is derived server-side and the algorithm can change without a client release.
  - `changeRequestId` string — Open structured PM request this repository sync deliberately applies. Requires expectedRepoBodyRevision and an API-key principal.
  - `expectedRepoBodyRevision` string — Exact base revision carried by changeRequestId. Both the request base and the current intent are compared atomically; a mismatch returns 409 CHANGE_REQUEST_BASE_CONFLICT.
  - `title` string — Non-empty after trim if provided. Stored as user_goal.
  - `objective` string — Non-empty after trim if provided.
  - `currentState` string — Author-written as-is behavior (max 4000 chars). An empty string clears the field (net-new capability has no current state).
  - `outcomes` OutcomeInput[] — Replaces both outcomes_v2 and the flat outcomes text list. Omit measurement on an outcome to preserve its stored recipe; send measurement: null to clear it explicitly.
    - union
      - string
      - object
        - `id` string
        - `text` string, required
        - `priority` 'must' | 'should' | 'could'
        - `measurement` OutcomeMeasurementDefinition — Provider-neutral recipe for evaluating an outcome with a stable saved query.
          - `source` object, required
            - `provider` string, required
            - `queryRef` object, required
              - …
          - `resultSelector` string — Optional path into a compound provider response.
          - `expectation` object, required
            - `operator` 'gt' | 'gte' | 'lt' | 'lte' | 'eq', required
            - `target` number, required
            - `unit` string
          - `window` object, required
            - `kind` 'rolling' | 'fixed' | 'since_ship', required
            - `duration` string — Required for rolling windows, e.g. 28d.
            - `start` string — Required with end for fixed windows.
            - `end` string — Required with start for fixed windows.
  - `constraints` string[] — Replaces constraints (coerced to trimmed non-empty strings).
  - `healthMetrics` string[] — Replaces health_metrics (coerced to trimmed non-empty strings).
  - `edgeCases` object[] — Replace-all semantics via replaceIntentEdgeCasesRpc; on failure the intent is rolled back to its prior snapshot and 500 returned.
  - `verification` object — Replaces the verification plan. checks is canonical; the three older buckets are compatibility inputs. Incoming check status is not trusted over the stored live status.
  - `problemSeverity` 'low' | 'medium' | 'high' | 'critical' — Nullable severity enum.
  - `evidenceAnchors` string — Map of anchor key (e.g. 'objective', 'outcome:<stable-outcome-id>', 'edgeCase:<stable-edge-case-id>', 'constraint:0') to evidence id arrays.
  - `scope` string — Nullable scope object.

## Response `200`

OK — returns the full updated intent (re-fetched with relations)

- object

## Other responses

- `400` — Invalid request body (zod) — { error, details }; OR no updatable field provided ('At least one field must be provided to update'); OR cookie-session auth missing workspace_id
- `401` — Invalid/expired API key, or no Bearer key and no valid session cookie
- `403` — Lacks write scope; OR cookie auth not a member of the workspace
- `404` — Intent not found (PGRST116) within this workspace (on snapshot or update)
- `409` — code VERSION_CONFLICT: expectedVersion no longer matches. Re-read the intent, reapply the edit on top, and retry with the new specVersion.
- `500` — DB error, edge-case sync failure (intent rolled back to prior snapshot), or unexpected internal error

## Changes

- **2026-09-01** `a660c0d36148` — 2 info
  - added the new optional request property `changeRequestId`
  - added the new optional request property `expectedRepoBodyRevision`
- **2026-08-31** `8ef75cba546a` — 4 breaking, 1 info
  - removed the enum value `could` of the request property `outcomes/items/`
  - removed the enum value `must` of the request property `outcomes/items/`
  - removed the enum value `should` of the request property `outcomes/items/`
  - the `outcomes/items/` request property type changed from `string` to no type
  - …1 more
- **2026-08-27** `e419abb0a327` — 2 breaking, 5 info
  - request property `outcomes/items/` was restricted to a list of enum values
  - the `edgeCases/items/` request property type changed from `string` to `object`
  - added the new optional request property `expectedVersion`
  - added the new `could` enum value to the request property `outcomes/items/`
  - …3 more
- **2026-08-23** `155c812b368b` — 6 info
  - added the new optional request property `currentState`
  - added the optional property `details` to the response with the `400` status
  - added the optional property `details` to the response with the `401` status
  - added the optional property `details` to the response with the `403` status
  - …2 more

[Change history](https://skmtc.dev/pathmode/apis/pathmode-api/changes/api/v1/intents/:id/patch.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/c7d545bf359b?raw)