intents

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

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.

patch/api/v1/intents/{id}

Path parameters

idstring required

id path parameter.

Query parameters

workspace_idstring

Required ONLY for cookie-session auth; identifies the target workspace. Ignored for API-key auth.

Request body

expectedVersionstring

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.

changeRequestIdstring

Open structured PM request this repository sync deliberately applies. Requires expectedRepoBodyRevision and an API-key principal.

expectedRepoBodyRevisionstring

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.

titlestring

Non-empty after trim if provided. Stored as user_goal.

objectivestring

Non-empty after trim if provided.

currentStatestring

Author-written as-is behavior (max 4000 chars). An empty string clears the field (net-new capability has no current state).

constraintsstring[]

Replaces constraints (coerced to trimmed non-empty strings).

healthMetricsstring[]

Replaces health_metrics (coerced to trimmed non-empty strings).

edgeCasesobject[]

Replace-all semantics via replaceIntentEdgeCasesRpc; on failure the intent is rolled back to its prior snapshot and 500 returned.

verificationobject

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.

evidenceAnchorsstring

Map of anchor key (e.g. 'objective', 'outcome:<stable-outcome-id>', 'edgeCase:<stable-edge-case-id>', 'constraint:0') to evidence id arrays.

scopestring

Nullable scope object.

Example request

{
  "outcomes": [
    {
      "measurement": {
        "source": {
          "provider": "posthog",
          "queryRef": {
            "kind": "saved_insight"
          }
        }
      }
    }
  ]
}

Response

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

object required

Changes

Changed in 4 of the 14 revisions of this API.614

Sep 1, 2026a660c0d361482See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
Aug 31, 20268ef75cba546a41See the full diff
- ▲
  removed the enum value could of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value must of the request property /
  request-property-enum-value-removed
- ▲
  removed the enum value should of the request property /
  request-property-enum-value-removed
- ▲
  the / request property type changed from string to no type
  request-property-type-changed
- ○
  added subschema #1 subschema #2 to the / request property oneOf list
  request-property-one-of-added
Aug 27, 2026e419abb0a32725See the full diff
- ▲
  request property / was restricted to a list of enum values
  request-property-became-enum
- ▲
  the / request property type changed from string to object
  request-property-type-changed
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new could enum value to the request property /
  request-property-enum-value-added
- ○
  added the new must enum value to the request property /
  request-property-enum-value-added
- ○
  added the new should enum value to the request property /
  request-property-enum-value-added
- ○
  added the non-success response with the status
  response-non-success-status-added
Aug 23, 2026155c812b368b6See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added
- ○
  added the optional property to the response with the status
  response-optional-property-added

Full history