Clear every draft outcome

Clear every draft outcome

Required scopes: interview_plans:write

Empties the outcomes stage. Nothing downstream is pruned — competencies, skills, rounds, and questions keep their content and their own versions.

Clearing is explicit, and it is the only way to empty a stage. Where a stage has an item-level delete_* action it refuses to remove the last item, and outcomes have no item-level delete at all, so an empty stage can only be reached through this verb. The stage is written as an empty list, its version bumps, and source_metadata.<stage>.cleared_version records the version at which it was cleared — so the emptied section still reads as addressed, not never filled in.

A cleared draft cannot be published as a new plan. Draft validation still requires items in every stage, so a draft with a cleared section will not reach validated. That is the intended shape of the verb, not a gap: the onward action is POST /v1/interview_plans/actions/modify_active, which binds the emptying onto an already-live plan.

No confirmation field. Clearing takes no acknowledgement flag. Nothing is lost at this point — the draft is a working copy, and the emptying only reaches candidates when a caller previews and binds it onto the live plan.

Verbatim edit. The draft stores exactly what you send — no AI generation, no rewriting; the same request always produces the same stored content. The response echoes the stored stage content plus the full stage_versions map.

Fetch-modify-submit with source_stage. Read the draft with GET /v1/interview_plan_drafts/{draft_id}, take the edited stage's version from stage_versions, and pass it as source_stage: {stage, version}. If the stage changed since your read, the edit returns 409 stale_source_stage instead of overwriting it. Editing a stage whose prerequisite checkpoint is missing returns 409 stage_prerequisite_missing.

Atomic write. Every mutated stage's version bumps in one write, and a validated draft rolls back to draft so validation reflects the new content.

Writes return data.audit with audit/event ids. Successful write events and audit rows include the resource type, public draft id, action key, request context, livemode partition, and a redacted payload summary. Use Idempotency-Key on retries; replayed requests return the cached response and do not duplicate draft checkpoints, audit rows, or events.

Example (curl):

curl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_outcomes \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"action":"interview_plan.clear_outcomes","resource":{"type":"interview_plan_draft","id":"ipd_…"},"input":{"source_stage":{"stage":"outcomes","version":3}}}'

Example (TypeScript):

await fetch("https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_outcomes", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "action": "interview_plan.clear_outcomes",
  "resource": {
    "type": "interview_plan_draft",
    "id": "ipd_…"
  },
  "input": {
    "source_stage": {
      "stage": "outcomes",
      "version": 3
    }
  }
}),
});