Record a goal progress event.

Record a goal progress event.

post/v1/goals/progress

Request

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

goal_idstring required

The goal this progress belongs to, by its id or the goal_key you gave it.

kind'contribution' | 'withdrawal' | 'adjustment' required

Whether this event adds to the goal, takes from it, or corrects it. Withdrawals and adjustments net against observed progress, so the running total is a balance rather than a sum of deposits.

notestring
occurred_atinteger

When the progress happened, as milliseconds since the Unix epoch; the ceiling is the last millisecond of 9999-12-31, the latest time with a four-digit calendar date. Omitted means now.

Response

Goal progress 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.