Store an agent-authored category budget plan.

Store an agent-authored category budget plan.

post/v1/budget/plan

Request

  • Base URL: https://api.candor.money
  • URL: https://api.candor.money/v1/budget/plan
  • 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

periodstring required

The month this plan governs, as YYYY-MM.

currencystring required

Three-letter uppercase ISO code the plan is denominated in, such as USD. Every line amount is read in it, so a plan in the wrong currency compares against the wrong spending.

approval_notestring

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

approval_sourcestring

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

policy_notesstring
recurs_monthlyboolean

Whether this plan should carry into later months instead of applying to this period alone.

Response

Envelope with the active budget plan, plan lines, and superseded plan ids.

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.