---
title: "Clear every draft job skill"
method: POST
path: "/v1/interview_plan_drafts/actions/clear_job_skills"
tags: ["Interview Plan Builder"]
---

# Clear every draft job skill

`POST /v1/interview_plan_drafts/actions/clear_job_skills`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_job_skills`
- Auth: HTTP bearer

Clear every draft job skill

**Required scopes:** `interview_plans:write`

Empties the job skills stage. Skills have no dependent keyed data, so nothing is pruned.

**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):**

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

**Example (TypeScript):**

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

## Headers

- `Idempotency-Key` string
- `X-Request-Id` string

## Request body

- object
  - `action` 'interview_plan.clear_job_skills', required
  - `resource` object
    - `type` 'interview_plan_draft', required
    - `id` string
  - `input` object, required
    - `source_stage` object
      - `stage` 'skills', required
      - `version` integer

## Response `200`

Success

- StagedBuilderActionResponse: Staged interview-plan builder checkpoint response, shared by the generation stages and the verbatim edit actions. `data` echoes the stored stage content (including prune reports on cascading deletes) and `checkpoint.stage_versions` carries the per-stage versions used for `source_stage` preconditions.
  - `resource` object, required
    - `type` 'interview_plan_draft' | 'interview_plan', required
    - `id` string, nullable, required
  - `action` 'interview_plan.generate_outcomes' | 'interview_plan.confirm_outcomes' | 'interview_plan.generate_competencies' | 'interview_plan.generate_skills' | 'interview_plan.generate_rounds' | 'interview_plan.add_rounds' | 'interview_plan.update_rounds' | 'interview_plan.delete_rounds' | 'interview_plan.generate_anchors' | 'interview_plan.generate_questions_directions' | 'interview_plan.add_competencies' | 'interview_plan.update_competencies' | 'interview_plan.delete_competencies' | 'interview_plan.add_skills' | 'interview_plan.update_skills' | 'interview_plan.delete_skills' | 'interview_plan.clear_outcomes' | 'interview_plan.clear_competencies' | 'interview_plan.clear_job_skills' | 'interview_plan.clear_interview_sequence' | 'interview_plan.validate_draft' | 'interview_plan.publish' | 'interview_plan.modify_active' | 'interview_plan.add_questions' | 'interview_plan.update_questions' | 'interview_plan.delete_questions' | 'interview_plan.update_round_directions' | 'interview_plan.update_anchors' | 'interview_plan.delete_anchors', required
  - `execution_mode` 'draft_write' | 'interactive_gate' | 'validate_only' | 'approval_required' | 'blocked_until_verified', required
  - `approval` object, required
    - `gate` 'none' | 'agent_confirmable' | 'dashboard_required', required
    - `required` boolean, required
    - `reason` string, required
  - `stage` string, required
  - `data` object, required
    - `status` 'checkpointed' | 'generated' | 'generation_pending' | 'validated' | 'not_ready' | 'unsupported_stage' | 'approval_required' | 'blocked', required
    - `message` string, required
    - `outcomes` object[]
    - `competencies` object[]
    - `job_skills` object[]
    - `interview_sequence` object[]
    - `questions_and_directions` object
    - `behavioral_anchors` object
    - `round_id` string
    - `questions` object[]
    - `interviewer_directions` string, nullable
    - `candidate_directions` string, nullable
    - `pruned_behavioral_anchor_ids` string[]: Item ids whose behavioral anchors were pruned because their competency was deleted in this request.
    - `pruned_question_round_ids` string[]: Round ids whose questions and directions were pruned because the round was deleted in this request.
    - `generated_round_ids` string[]
    - `generated_competency_ids` string[]
    - `preview` object
    - `affected_counts` object
    - `audit` object
      - `audit_id` string
      - `event_id` string
      - `audit_log` string, required
      - `api_event` string, required
  - `checkpoint` object
    - `stage` string, required
    - `version` integer, required
    - `stage_versions` object, required
  - `validation` object, required
    - `status` 'not_evaluated' | 'ready' | 'blocked', required
    - `publish_ready` boolean, required
    - `blockers` object[], required
      - `code` string, required
      - `message` string, required
      - `path` string
      - `next_action` string
    - `warnings` object[], required
      - `code` string, required
      - `message` string, required
      - `path` string
      - `next_action` string
  - `next_actions` string[], required
  - `web_url` string, nullable, required
  - `request_id` string, required
  - `warnings` object[]: Non-blocking signals emitted by this action (e.g., department_mismatch when source_job_id seeding produced a Department override). Omitted when empty.
    - `code` string, required: Machine-readable warning code (e.g. department_mismatch).
    - `message` string, required
    - `detail` object

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Conflict (e.g. idempotency key reuse with different body)
- `429`: Rate limited
- `500`: Internal error

---

[API](https://skmtc.dev/yardstick/apis/yardstick-public-api.md) · [All operations](https://skmtc.dev/yardstick/apis/yardstick-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yardstick/apis/yardstick-public-api/revisions/35b5a6e88b35?raw)