--- title: "Save a goal the person is working toward, with the measure that tracks it." method: POST path: "/v1/goals" --- # Save a goal the person is working toward, with the measure that tracks it. `POST /v1/goals` ## Request - Base URL: `https://api.candor.money` - URL: `https://api.candor.money/v1/goals` - Auth: HTTP bearer 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. ## Headers - `Idempotency-Key` string, required ## Request body - GoalCreateRequest: Something the user is working toward, saved from what they said. Use their words and only figures and dates they gave or the records show; leave out anything they have not said. - `approval_note` string: 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_source` string: Where their words came from, such as the conversation or message, when you pass approval_note. - `contribution_amount` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - `contribution_cadence` 'weekly' | 'biweekly' | 'monthly' | 'quarterly' | 'annual' - `goal_key` string, 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. - `measure` union: What a goal's progress is read from. Pick the figure that tells whether the person is getting there; Candor keeps it current from their records and raises it when it falls behind its plan, so neither of you has to work it out again. Balances: accounts (the accounts that hold the goal's money), account_share (an amount or a percent of one account), debt (cards or loans paid down since the measure was set). Monthly figures: tagged (money in, money out, or the net each full month across the transactions carrying tags your rules set; for anything the records show that no balance holds, such as what a venture brings in, what a property nets, or what a commitment costs; tag the transactions first with rules.create add_tags), spending (the household's monthly spending), and cover (how many months of that spending named accounts cover). A monthly target can be a floor or a ceiling (target_bound) and can be zero. recorded: progress you record, for what the records cannot show. Set the measure as soon as you know which money counts; it needs no target and no further sign-off (tagged takes none; cover's target_amount or target_months and accounts' target_amount are optional), and the figure starts tracking at once. An ambition that needs several of these is several goals, each with its own measure and parent_goal_id naming the goal they serve. Measure only money the person counts toward the goal, and save a cushion, account, or step they did not name with proposed true, so it shows as your suggestion until they take it on. Linking an account does not earmark it, and an account that holds one goal outright cannot hold another. - object - `kind` 'accounts', required: Read from the accounts that hold the goal's money. - `account_ids` string[], required: Ids from accounts list of the accounts that hold the goal's money. - `held_elsewhere` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - object: Either amount or percent, not both. Shares of one account cannot add up to more than it holds. - `kind` 'account_share', required: Read from an amount or a percent of one account. - `account_id` string, required: The id from accounts list of the account the share is of. - `amount` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - `percent` number - `held_elsewhere` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - object - `kind` 'debt', required: Read from what the goal's cards or loans owe, paid down since it was set. - `account_ids` string[], required: Ids from accounts list of the cards or loans the goal pays down. - object - `kind` 'tagged', required: A monthly figure of transactions carrying any of these tags, averaged over full months, as count says (money in less money out, when absent). The goal's target_amount is the monthly figure, a floor or with target_bound at_most a ceiling; contribution_amount and saved_so_far do not apply. - `tags` string[], required: Tags your rules set on transactions (rules.create add_tags), matched without regard to case. Tag income and costs alike when the figure is a net; a rule keeps tagging new transactions as they arrive. - `months` integer: Full months to average over; 3 when omitted. The current month is not in the average, since it is not over; progress reports it beside the average as this_month, through today. - `count` 'net' | 'in' | 'out': Which monthly figure: net (money in less money out, the default) for what something nets, such as a business that should pay for itself; in for what comes in; out for what goes out, as a positive amount, such as what a habit or a commitment costs. - object - `kind` 'spending', required: The household's monthly spending: purchases, bills, and loan installments from its cash and cards, averaged over the last three full months, the same figure the attention review and cover read. With target_amount it is a ceiling (target_bound at_most) unless bound at_least; use it when what matters is living within an amount, such as base pay. Progress reports each month and the current month so far. - object - `kind` 'cover', required: What these accounts hold and the months of the household's spending that covers, divided by the same monthly spending the attention review reads. It does not set money aside, so checking counts and an account can cover several goals; this is how a cushion kept in everyday accounts is measured. - `account_ids` string[], required: Ids from accounts list of the accounts the household would live on. - `held_elsewhere` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - `target_months` number: The months of spending the person wants covered, when they think in months. When they named an amount instead, keep it as the goal's target_amount; either is the target. contribution_amount and saved_so_far do not apply. - object - `kind` 'recorded', required: The person reports progress by hand and you record it with goals progress. Choose it only when no figure in the records shows progress; it is not a default. - `parent_goal_id` string: 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. - `name` string, 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_notes` string - `set_by` string: 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. - `proposed` boolean: 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. - `saved_so_far` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - `next_step` GoalNextStep: The next step on a goal. The person sees only the line Candor renders from check (for example, "Your agent watches for the next charge from Ironworks"), so set check; a step without one reads as your agent checking back. A transaction check is evaluated against the records, and the opening says when it is answered. - `date` string, date, required: When, as YYYY-MM-DD; today or later. - `check` union: What the agent watches for, structured so Candor renders the person's line and can tell when it is answered. - object - `kind` 'transaction', required: Watch a payee in the records. Candor matches new transactions against it and the opening says when it is answered. - `payee` string, required: The payee as the transactions name it (merchant or description), matched without regard to case. - `expect` 'charge' | 'deposit' | 'no_charge', required: charge or deposit is answered when one posts; no_charge holds while none posts and breaks if one does. - object - `kind` 'figure' | 'ask' | 'review', required: figure checks the goal's own measure; ask is a question for the person; review is going over the plan with them. - `note` string: Your own note on this step, as specific as you like. The person never sees it; it comes back to you with the goal. - `text` string: The earlier free-text form, kept as your note. Prefer check and note. - `why` string: 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_amount` union: Exact Money input using a supported currency code, one space, and a plain signed decimal within Candor's supported range. - string - string - string - `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_date` string, 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 `200` Created goal envelope. - ResponseEnvelope - `schema_version` string, required - `generated_at` string, date-time, required - `request_id` string, required - `status` 'success' | 'partial_success' | 'action_required' | 'error', required - `user_message` string: Optional concise user-safe message the calling agent may adapt. - `data_freshness` DataFreshness - `balances_last_synced_at` string - `coverage` 'complete' | 'partial' | 'stale' | 'unavailable', required - `holdings_last_synced_at` string - `transactions_last_synced_at` string - `metadata` object: Response-level protocol metadata such as package compatibility and workspace opening identity or timing. It is not financial workspace data and must not be treated as attention. - `view_url` string, uri: Authenticated dashboard destination related to this response. May open a section rather than reproduce the returned records or filters. Per-record view_url values identify exact supported record views. Use returned URLs instead of constructing paths. - `warnings` object[], required - `errors` AgentError[], required - `code` string, required - `expires_at` string - `idempotency_key` string: Stable key to reuse when retrying this identical logical operation. - `message` string, required - `recovery_url` string, uri - `required_capability` string - `retry_after_seconds` integer: Machine-actionable delay before retrying the identical logical operation. - `retryable` boolean, required - `suggested_command` string - `next_actions` AgentAction[], required - `intent` string, required - `command` string, required - `args` object, required - `shell` string, required - `action` WorkspaceAction - `id` string, required - `operation` string, required - `reason` string, required - `root_action_id` string, required - `parent_action_id` string - `task_key` string - `status` 'started' | 'succeeded' | 'refused' | 'failed', required - `created_at` string, date-time, required - `completed_at` string, date-time - `data` object, nullable, required: Operation-specific result data, or null when the request ends in an error. ## Other responses - `default`: Structured Candor error envelope with machine-readable codes, recovery guidance, and retry timing when applicable. --- [API](https://skmtc.dev/candor/apis/candor-api.md) · [All operations](https://skmtc.dev/candor/apis/candor-api/llms.txt) · [OpenAPI document](https://skmtc.dev/candor/apis/candor-api/revisions/6c050f72e956?raw)