Create a new goal version.

Create a new goal version.

post/v1/goals/update

Request

  • Base URL: https://api.candor.money
  • URL: https://api.candor.money/v1/goals/update
  • Auth: HTTP bearer

Headers

Idempotency-Keystring required

Stable opaque identity for one logical POST. Reuse only with the same method, path, actor, and body for transport retries. A completed receipt replays its original result, including a refusal; changed input with the same key is rejected. After a refused action and access recovery, use a new key for the new attempt. Follow retryable and recovery guidance if the operation is still running or its outcome is unknown.

Request body

approval_notestring

What the user said about this change, in their words, when they said something. Optional.

approval_sourcestring

Where their words came from, when you pass approval_note.

contribution_cadence'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'annual' nullable
goal_idstring required

The goal's id, or the goal_key you gave it.

namestring
policy_notesstring nullable
set_bystring
status'active' | 'paused' | 'completed'
priority'high' | 'medium' | 'low' nullable

Where the person ranks this goal among theirs; null clears it. An update that only sets priority or next_step writes no new version.

proposedboolean

True when you suggested this goal or part and the person has not taken it on; their dashboard shows it as your suggestion and never leads with it. Set false once they agree.

parent_goal_idstring nullable

The goal this one is a part of; null makes it a goal of its own again. Like priority and next_step, it writes no new version.

whystring nullable

The person's reason in their own words; null removes it.

target_bound'at_least' | 'at_most'

For a monthly measure (tagged or spending): at_least when the target is a floor to reach or keep above, at_most when it is a ceiling to stay under. Omitted, a spending measure's target is at_most and a tagged one's at_least. Balance targets are amounts to reach and take no bound.

target_datestring date nullable

The new target date as YYYY-MM-DD; null removes the date. Omitted keeps the current one.

Response

Updated goal envelope.

schema_versionstring required
generated_atstring date-time required
request_idstring required
status'success' | 'partial_success' | 'action_required' | 'error' required
user_messagestring

Optional concise user-safe message the calling agent may adapt.

warningsobject[] required
dataobject nullable required

Operation-specific result data, or null when the request ends in an error.

Changes

No recorded changes to this operation across all 1 revision of this API.