Skip to main content

Correct Goal Baseline

POST 
/api/success-plan/goals/:goal/baseline

Records a corrected baseline. The old baseline is kept and marked superseded, and the correction is logged with its reason. In retrospective mode, a goal with no "before" yet takes its first baseline here and no reason is needed.

Required scope: success_plan:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Authentication: Requires Bearer token with the success_plan:write scope. The user must hold the success_plan.manage permission.

Send the baseline fields at the top level (or nested under baseline), plus:

  • reason (string, 3–255): why it is being corrected. Required when the goal already has a baseline.

Fields:

  • value (number): the figure. Required unless use_measured / use_imported is true, or the unit is hours_per_week (send roles) or boolean (send value_bool). 0–100 for percentage units; zero or more for counts, units and days.
  • value_bool (boolean): yes / no for boolean goals.
  • roles (array, 1–20): hours by role for hours_per_week goals; each row is role (string, required, max 60) and hours_per_week (number 0–168, required). The value is the total. Not allowed on other units.
  • as_of (date, Y-m-d): when the figure was true. Required with a typed value; never in the future; at most 365 days back (in retrospective mode, back to the start of the month before go-live).
  • evidence (string): how you know it: document, system_export or estimate (recall is also accepted in retrospective mode). Required with a typed value. Ignored with use_measured / use_imported: SKU.io records its own figure as system.
  • source_note (string, max 255): where the figure came from.
  • range_low, range_high (number): only with estimate or recall; required with recall. The value must sit inside the range.
  • confidence (string): high, medium or low; only with estimate or recall; required with recall.
  • attachment_ids (integer array, max 10): uploaded evidence files; only with document or system_export evidence.
  • use_measured (boolean): use SKU.io's measured figure for last month instead of a typed value (measured templates only).
  • use_imported (boolean): retrospective mode only; use orders imported from before go-live.

Returns the goal with its new baseline. Refused writes answer 422 with a machine-readable code alongside the usual errors, where each error is {message, code}: max_active_goals (three active goals at most; archive one first), measured_baseline_unavailable, imported_baseline_unavailable, baseline_required, unit_not_allowed, goal_archived, goal_has_target.

409 goal_busy: SKU.io was measuring this goal and did not finish in time; nothing was saved, so retry shortly.

Request​

Responses​

OK

Response Headers
    Content-Type