Update or reorder draft interview rounds verbatim

Update or reorder draft interview rounds verbatim

Required scopes: interview_plans:write

Replaces rounds by id and/or reorders the stage. order must be a complete permutation of the resulting round ids; pure reorder works with order alone.

Update in place does not prune. A round replaced via update_rounds keeps its id, and its questions and directions in the questions_and_directions checkpoint are preserved — pruning only happens on delete_rounds. This is what makes id-preserving replacement the safe way to swap a full stage's content.

Count invariants. The interview rounds stage must hold between 1 and 20 items after every edit: deleting the last item or adding past 20 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see clear_*.

Replacing a full stage. When the stage is at its 20-item maximum, replace content with update_* against the existing ids — an item updated in place keeps its id, and its dependent data is NOT pruned. If you must swap ids, interleave add_*/delete_* in capacity-sized batches so every intermediate state stays within the limits.

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.

Item ids. Unknown item ids return 404 draft_item_not_found naming the id. Caller-supplied ids that duplicate an existing id, or repeat within one request, are rejected naming the id; omitted ids on add_* are minted server-side and never collide with existing ids.

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/update_rounds \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -d '{"action":"interview_plan.update_rounds","resource":{"type":"interview_plan_draft","id":"ipd_…"},"input":{"items":[{"id":"round_1","title":"Recruiter Screen","description":"Motivation, logistics, and mutual fit.","duration":30}],"source_stage":{"stage":"interview_sequence","version":4}}}'

Example (TypeScript):

await fetch("https://api.yardstick.team/v1/interview_plan_drafts/actions/update_rounds", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.YS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
  "action": "interview_plan.update_rounds",
  "resource": {
    "type": "interview_plan_draft",
    "id": "ipd_…"
  },
  "input": {
    "items": [
      {
        "id": "round_1",
        "title": "Recruiter Screen",
        "description": "Motivation, logistics, and mutual fit.",
        "duration": 30
      }
    ],
    "source_stage": {
      "stage": "interview_sequence",
      "version": 4
    }
  }
}),
});