Save a goal the person is working toward, with the measure that tracks it.

Save something the person is working toward, in their words, as soon as they describe it; numbers can come later with goals.update. Give it the measure that reads progress from their records, so Candor keeps the figure current between conversations and raises it when it falls behind; measure says which figure fits. One ambition with several figures is several goals, each naming the goal it serves with parent_goal_id.

post/v1/goals

Request

  • Base URL: https://api.candor.money
  • URL: https://api.candor.money/v1/goals
  • 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 goal, in their words, when they said something. Optional: save goals from the conversation without asking for a yes, and edit them when they change.

approval_sourcestring

Where their words came from, such as the conversation or message, when you pass approval_note.

contribution_cadence'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'annual'
goal_keystring required

Stable identifier you choose and reuse, such as shop-pays-for-itself. Every goal operation takes it wherever it takes goal_id, so a later session can name the goal without listing goals first; keep it durable and descriptive.

kind'sinking_fund' | 'debt_reduction' | 'reserve' | 'purchase' | 'income' | 'other' required

What sort of commitment this is, which decides how progress reads: a sinking fund accumulates, debt reduction pays down, a reserve is held rather than spent.

parent_goal_idstring

The goal this one is a part of, when one ambition the person described is tracked as several goals, each with the measure that fits it. Save a part only for a piece the person described. Name it by its id or goal_key. Parts show under their goal on the person's dashboard instead of competing with it for focus. One level deep, so a part has no parts of its own.

namestring required

What the user calls this goal, as a short phrase their dashboard heads it with, in words they would say rather than a slug. Leave dates, figures, and asides out of it; they belong in the target fields, why, or a note.

policy_notesstring
set_bystring

Who set the goal, when it was not you acting alone.

priority'high' | 'medium' | 'low'

Where the person ranks this goal among theirs. Their dashboard leads with the first; ties go to the sooner target date. Record what they said, never your own ranking.

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.

whystring

The person's reason for this goal in their own words, such as "so the kids have their own rooms". Their dashboard shows it under the goal, so write it as a phrase that reads on its own, not notes.

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

The calendar date the target is meant to be met by, as YYYY-MM-DD. Time left, the contribution the date requires, and the trajectory all count toward it; a timestamp or a phrase is refused.

Response

Created 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.