{"openapi":"3.1.0","info":{"title":"Yardstick Public API","version":"2026-05-02","description":"Public REST API for the Yardstick hiring platform. Resources are addressable by stable display IDs (e.g. `per_…`, `app_…`, `opp_…`). All responses are JSON; errors share a single `{error: …}` envelope.\n\n**Canonical resources:** use People for person identity, Jobs for internal hiring containers, Applications for person + Job attachments and application-owned writes, Opportunities for read-only candidate/interview-cycle work views, and Job Postings for candidate-facing publish/archive flows. If a user asks an agent to create or add a candidate, create or reuse a Person and then create an Application; Opportunities remain read-only next-action and dashboard-handoff views.\n\n**Versioning:** breaking changes require a `/v2/` prefix. Within `/v1/`, additive changes (new fields, new endpoints) are non-breaking.\n\n**Modes:** every token is bound to a `live` or `test` partition. Data from the two modes never crosses over."},"servers":[{"url":"https://api.yardstick.team","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"People","description":"People are stable identity records for applicants, leads, or contacts. Browser-safe publishable keys may only create people for intake; listing, retrieval, and updates require secret keys. Create or reuse a Person before creating an Application for a job."},{"name":"Applications","description":"Canonical person + Job attachment and application write surface. Use POST /v1/applications when a user asks to create or add a candidate for a job; status transitions, archive flows, and Application Review detail belong to Applications."},{"name":"Opportunities","description":"Read-only enriched candidate/interview-cycle work views over applications, with next-action and dashboard deep-link helpers."},{"name":"Reporting","description":"Bounded reporting search over canonical V1 recruiting reporting families. Mode comes from the API token; requests must supply explicit windows."},{"name":"Jobs","description":"Internal hiring containers. Jobs are distinct from candidate-facing Job Postings and their publish/archive approval flows."},{"name":"Departments","description":"Canonical Department resources, members, and invitation views."},{"name":"Job Postings","description":"Job posting drafts, publish, and archive. Publish and archive use a preview→bind approval flow."},{"name":"Events","description":"Customer-facing event log."},{"name":"Communications","description":"Read-only candidate email draft list, detail, preview, history, and provenance."},{"name":"Audit","description":"Audit log of API-driven mutations."},{"name":"Operations","description":"Operational read-only diagnostics exposed through schema-bound, redacted public API routes."},{"name":"Auth","description":"Token introspection."},{"name":"Interview Plan Builder","description":"Staged interview-plan draft actions, including non-mutating not-ready and approval-preview responses."},{"name":"Interview Plans","description":"Read-only interview plan resources with redacted round structure."},{"name":"Interview Sessions","description":"Read-only interview session resources and application-scoped session lists."},{"name":"Scheduling","description":"Interview session scheduling readiness and provider-agnostic link generation. Blocked sessions return structured setup or plan-lineage `blocker_code` values matching the dashboard recovery flows."},{"name":"Interview Evaluation","description":"Interview session lifecycle (start/complete), scorecard submission, decision brief read/regenerate, and final-recommendation recording. Routes enforce organization and live/test partitioning through the session or application and return safe not-found responses for cross-org or wrong-mode probes."},{"name":"Roles","description":"Role assignments and the v1 system role catalog."},{"name":"Tasks","description":"User-scoped task queue and deep-link resolution. The list endpoint returns the authenticated token principal's open and completed tasks; the deep-link endpoint resolves a `tsk_…` id to a dashboard URL. Both endpoints require the secret-only `tasks:read` scope and resolve the principal server-side from `api_tokens.created_by`. Tasks are partitioned by mode; survey tasks are live-only by design."}],"paths":{"/v1/roles":{"get":{"tags":["Roles"],"summary":"List the v1 system roles and their permission matrix.","operationId":"listSystemRoles","responses":{"200":{"description":"The 5 v1 system roles (admin, recruiter, department_lead, hiring_manager, interviewer).","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Role"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/v1/role_assignments":{"get":{"tags":["Roles"],"summary":"List role assignments in the actor's organization.","operationId":"listRoleAssignments","parameters":[{"name":"user_id","in":"query","schema":{"type":"string","pattern":"^per_[A-Z0-9]{26}$"}},{"name":"role","in":"query","schema":{"type":"string","enum":["admin","recruiter","department_lead","hiring_manager"]}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":50}}],"responses":{"200":{"description":"Paginated role assignments.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignmentList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"post":{"tags":["Roles"],"summary":"Grant a role at a scope.","operationId":"createRoleAssignment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["user","role","scope"],"properties":{"user":{"type":"string","pattern":"^per_[A-Z0-9]{26}$"},"role":{"type":"string","enum":["admin","recruiter","department_lead","hiring_manager"]},"scope":{"$ref":"#/components/schemas/RoleAssignmentScope"}}}}}},"responses":{"201":{"description":"Role assignment created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignment"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}}},"/v1/role_assignments/{id}":{"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","pattern":"^rola_[A-Z0-9]{26}$"}}],"get":{"tags":["Roles"],"summary":"Get one role assignment.","operationId":"getRoleAssignment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}},"patch":{"tags":["Roles"],"summary":"No-op-or-422: PATCH accepts the same body as POST but only succeeds if it matches the existing row. Reserved for forward-compatibility.","operationId":"patchRoleAssignment","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"user":{"type":"string","pattern":"^per_[A-Z0-9]{26}$"},"role":{"type":"string","enum":["admin","recruiter","department_lead","hiring_manager"]},"scope":{"$ref":"#/components/schemas/RoleAssignmentScope"}}}}}},"responses":{"200":{"description":"No-op succeeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RoleAssignment"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"},"422":{"$ref":"#/components/responses/UnprocessableEntity"}}},"delete":{"tags":["Roles"],"summary":"Revoke a role assignment.","operationId":"deleteRoleAssignment","responses":{"204":{"description":"Deleted."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/v1/people":{"post":{"operationId":"createPeople","summary":"Create a person","description":"Create a person\n\n**Required scopes:** `people:write`\n\nAccepts both publishable (`ys_pk_*`) and secret (`ys_sk_*`) keys. Use a publishable key when posting from a browser intake form (the example below); use a secret key with `people:write` for server-to-server flows — the canonical create path before `POST /v1/applications`, which requires `person_id`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/people \\\n  -H 'Authorization: Bearer ys_pk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"email\":\"alex@example.com\",\"name\":\"Alex Lee\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/people\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({ email: \"alex@example.com\", name: \"Alex Lee\" }),\n});\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":"string","maxLength":50},"linkedin_url":{"type":"string","format":"uri","maxLength":2048},"resume_url":{"type":"string","format":"uri","maxLength":2048},"notes":{"type":"string","maxLength":10000}},"additionalProperties":false}}}}},"get":{"operationId":"listPeople","summary":"List people","description":"List people\n\n**Required scopes:** `people:read`\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/people?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/people?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Person"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Return only the Person with this exact email. Use it to find the existing record after a `candidate_email_conflict`.","schema":{"type":"string","format":"email"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/people/{person_id}":{"get":{"operationId":"retrievePeoplePerson_id","summary":"Retrieve a person","description":"Retrieve a person\n\n**Required scopes:** `people:read`\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/people/per_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/people/per_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updatePeoplePerson_id","summary":"Update a person","description":"Update a person\n\n**Required scopes:** `people:write`\n\n**Example (curl):**\n\n```bash\ncurl -X PATCH https://api.yardstick.team/v1/people/per_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"phone\":\"+1-555-0100\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/people/per_abc123\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ phone: \"+1-555-0100\" }),\n});\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":500},"email":{"type":"string","format":"email","maxLength":320},"phone":{"type":"string","maxLength":50,"nullable":true},"linkedin_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"resume_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true}},"additionalProperties":false}}}}}},"/v1/people/{person_id}/resume_upload_sessions":{"post":{"operationId":"createResumeUploadSession","summary":"Create a resume upload session","description":"Create a resume upload session\n\n**Required scopes:** `people:write`\n\nServer-mediated signed upload-session. Returns a single-path, short-lived (≤5 min), one-shot signed Storage `upload_url`. Upload the PDF or DOCX bytes to that URL with an HTTP `PUT`, then call the finalize endpoint to attach and parse the resume. Secret keys (`ys_sk_*`) only.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/people/per_abc123/resume_upload_sessions \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"file_name\":\"resume.pdf\",\"size_bytes\":48211,\"content_type\":\"application/pdf\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/people/per_abc123/resume_upload_sessions\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n      file_name: \"resume.pdf\",\n      size_bytes: 48211,\n      content_type: \"application/pdf\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"201":{"description":"Resume upload session created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResumeUploadSession"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string","minLength":1,"maxLength":255},"size_bytes":{"type":"integer","minimum":1,"maximum":10485760},"content_type":{"type":"string","minLength":1,"maxLength":255}},"required":["file_name","size_bytes"],"additionalProperties":false}}}}}},"/v1/people/{person_id}/resume_upload_sessions/{session_id}/finalize":{"post":{"operationId":"finalizeResumeUploadSession","summary":"Finalize a resume upload session","description":"Finalize a resume upload session\n\n**Required scopes:** `people:write`\n\nRe-validates the uploaded object, attaches it as the person's resume, and parses it for each of the person's linked applications. Idempotent: re-finalizing a consumed session returns the person without re-attaching or re-parsing. Call after the bytes have been PUT to the session's `upload_url`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/people/per_abc123/resume_upload_sessions/rus_abc123/finalize \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/people/per_abc123/resume_upload_sessions/rus_abc123/finalize\",\n  {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n  },\n).then((r) => r.json());\n```","tags":["People"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Resume attached to the person.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Person"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/people/{person_id}/documents/upload_sessions":{"post":{"operationId":"createPeoplePerson_idDocumentsUpload_sessions","summary":"POST /v1/people/{person_id}/documents/upload_sessions","description":"POST /v1/people/{person_id}/documents/upload_sessions\n\n**Required scopes:** `people:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string","minLength":1,"maxLength":255},"size_bytes":{"type":"integer","minimum":1,"maximum":10485760},"content_type":{"type":"string","minLength":1,"maxLength":255},"kind":{"type":"string","enum":["resume","other"]},"label":{"type":"string","minLength":1,"maxLength":200}},"required":["file_name","size_bytes","kind","label"],"additionalProperties":false}}}}}},"/v1/people/{person_id}/documents/upload_sessions/{session_id}/finalize":{"post":{"operationId":"createPeoplePerson_idDocumentsUpload_sessionsSession_idFinalize","summary":"POST /v1/people/{person_id}/documents/upload_sessions/{session_id}/finalize","description":"POST /v1/people/{person_id}/documents/upload_sessions/{session_id}/finalize\n\n**Required scopes:** `people:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/people/{person_id}/documents":{"get":{"operationId":"listPeoplePerson_idDocuments","summary":"GET /v1/people/{person_id}/documents","description":"GET /v1/people/{person_id}/documents\n\n**Required scopes:** `people:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/people/{person_id}/documents/{document_id}":{"patch":{"operationId":"updatePeoplePerson_idDocumentsDocument_id","summary":"PATCH /v1/people/{person_id}/documents/{document_id}","description":"PATCH /v1/people/{person_id}/documents/{document_id}\n\n**Required scopes:** `people:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"label":{"type":"string","minLength":1,"maxLength":200}},"required":["label"],"additionalProperties":false}}}}},"delete":{"operationId":"deletePeoplePerson_idDocumentsDocument_id","summary":"DELETE /v1/people/{person_id}/documents/{document_id}","description":"DELETE /v1/people/{person_id}/documents/{document_id}\n\n**Required scopes:** `people:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/people/{person_id}/documents/{document_id}/download_url":{"post":{"operationId":"createPeoplePerson_idDocumentsDocument_idDownload_url","summary":"POST /v1/people/{person_id}/documents/{document_id}/download_url","description":"POST /v1/people/{person_id}/documents/{document_id}/download_url\n\n**Required scopes:** `people:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/people/{person_id}/documents/{document_id}/set_resume":{"post":{"operationId":"createPeoplePerson_idDocumentsDocument_idSet_resume","summary":"POST /v1/people/{person_id}/documents/{document_id}/set_resume","description":"POST /v1/people/{person_id}/documents/{document_id}/set_resume\n\n**Required scopes:** `people:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["people:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications":{"post":{"operationId":"createApplications","summary":"Create an application","description":"Create an application\n\n**Required scopes:** `applications:write`\n\nUse this endpoint when a user asks to create or add a candidate for a job. Create or reuse the Person first, then create the Application; the resulting record appears through read-only opportunity views and the app's Candidates surfaces. If the prerequisite Person is unavailable, the response is 404 `person_not_found` with `param: person_id`; if the prerequisite Job Posting is unavailable, it is 404 `job_posting_not_found` with `param: job_posting_id`. A later application read still uses `application_not_found` with `param: application_id`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"person_id\":\"per_abc123\",\"job_posting_id\":\"jp_xyz789\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/applications\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({\n    person_id: \"per_abc123\",\n    job_posting_id: \"jp_xyz789\",\n  }),\n});\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","minLength":1},"job_posting_id":{"type":"string","minLength":1}},"required":["person_id","job_posting_id"],"additionalProperties":false}}}}},"get":{"operationId":"listApplications","summary":"List applications","description":"List applications\n\n**Required scopes:** `applications:read`\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/applications?person_id=per_abc123&limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications?person_id=per_abc123&limit=20\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Application"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"job_id","in":"query","required":false,"description":"Filter applications by job_ public display id.","schema":{"type":"string"}},{"name":"person_id","in":"query","required":false,"description":"Filter applications by canonical `per_...` person id.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter applications by current status.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications/{application_id}":{"get":{"operationId":"retrieveApplicationsApplication_id","summary":"Retrieve an application","description":"Retrieve an application\n\n**Required scopes:** `applications:read`\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/applications/app_def456 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/applications/app_def456\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateApplicationsApplication_id","summary":"Update application stage","description":"Update application stage\n\n**Required scopes:** `applications:write`\n\n**Example (curl):**\n\n```bash\ncurl -X PATCH https://api.yardstick.team/v1/applications/app_def456 \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"stage\":\"Phone Screen\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/applications/app_def456\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ stage: \"Phone Screen\" }),\n});\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage":{"type":"string","maxLength":200}},"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/decide":{"post":{"operationId":"createApplicationsApplication_idActionsDecide","summary":"Decide on an application","description":"Decide on an application\n\n**Required scopes:** `tasks:write`\n\nRecords the job hiring manager's decision without a review task; `reject` disqualifies the candidate. Only the job's hiring manager may decide. Any other caller gets the same 404 `application_not_found` as an unknown application. `reason_code_ids` must be system reason codes or your organization's own; any other id returns 400 `invalid_request_body`. If the hiring manager is refused for another reason, such as Application Review being off or the application being archived, the response is 403 `application_decision_forbidden`. An application that already has a handoff or decision returns 409 `precondition_failed`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/decide \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"decision\":\"reject\",\"note\":\"Missing required experience\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/actions/decide\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      decision: \"reject\",\n      note: \"Missing required experience\",\n    }),\n  },\n);\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["tasks:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","approve_and_schedule","reject","hold","ask_recruiter"]},"note":{"type":"string","maxLength":10000},"reason_code_ids":{"type":"array","items":{"type":"string","format":"uuid"}}},"required":["decision"],"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/admit_candidate":{"post":{"operationId":"createApplicationsApplication_idActionsAdmit_candidate","summary":"POST /v1/applications/{application_id}/actions/admit_candidate","description":"POST /v1/applications/{application_id}/actions/admit_candidate\n\n**Required scopes:** `applications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/undo_candidate_admission":{"post":{"operationId":"createApplicationsApplication_idActionsUndo_candidate_admission","summary":"POST /v1/applications/{application_id}/actions/undo_candidate_admission","description":"POST /v1/applications/{application_id}/actions/undo_candidate_admission\n\n**Required scopes:** `applications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"expected_admission_id":{"type":"string","format":"uuid"}},"required":["expected_admission_id"],"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/transition_status":{"post":{"operationId":"createApplicationsApplication_idActionsTransition_status","summary":"Transition application status","description":"Transition application status\n\n**Required scopes:** `applications:write`, `applications:transition_status`\n\nNon-terminal transitions may write immediately. Sensitive terminal or provider-dependent transitions return approval-required or blocked envelopes; this route does not send communications, create scheduling links, update scorecards, publish jobs, archive records, or create reports. Target the move by `status` (resolved to the configured stage internally) or, additively, by `pipeline_stage_id` (move to a configured stage by id; `status` if also sent must equal the stage's mapped status). The same denied-state semantics apply either way: an unmet per-stage action gate returns HTTP 409 `action_gate_blocked`, and an approval-required target returns the HTTP 202 approval-preview envelope. A mutating response reports the resolved `pipeline_stage_id`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/transition_status \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"status\":\"Screening\",\"reason\":\"Meets baseline requirements\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/actions/transition_status\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      status: \"Screening\",\n      reason: \"Meets baseline requirements\",\n    }),\n  },\n);\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:write","applications:transition_status"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApplicationStatusTransitionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":2000},"employment_start_date":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false},"pipeline_stage_id":{"type":"string","minLength":1}},"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/status_email_approval_poc/preview":{"post":{"operationId":"createApplicationsApplication_idActionsStatus_email_approval_pocPreview","summary":"Preview status email approval POC","description":"Preview status email approval POC\n\n**Required scopes:** `applications:read`, `applications:write`, `applications:transition_status`, `applications:offer`, `communications:read`, `communications:write`\n\nApplications-owned POC preview→bind flow. This action is intentionally fixed to one explicit application, `Interviewing -> Offer`, `email_type=offer`, and `decision=review_edit`; unsupported transitions, decisions, send_now, natural-language targeting, bulk workflows, and autonomous sensitive sends are refused. Preview is mutation-free and returns the status side effect, reviewed-draft email side effect, sender/recipient/template provenance, approval binding fields, idempotency key, audit/event plan, and dashboard/API read-back hints. Bind requires the same Idempotency-Key as `binding.approved_idempotency_key`, verifies preview/input hashes and the resource version precondition, then records one status transition and one candidate email decision intent/draft effect. Events and evidence are redacted and do not expose provider secrets, OAuth tokens, raw provider payloads, raw prompt scaffolding, or candidate email addresses in API event payloads.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/status_email_approval_poc/preview \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: status-email-poc-preview-1' \\\n  -d '{\"current_status\":\"Interviewing\",\"target_status\":\"Offer\",\"email_type\":\"offer\",\"decision\":\"review_edit\",\"personalization_instruction\":\"Keep the offer note concise.\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/actions/status_email_approval_poc/preview\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": \"status-email-poc-preview-1\",\n    },\n    body: JSON.stringify({\n      current_status: \"Interviewing\",\n      target_status: \"Offer\",\n      email_type: \"offer\",\n      decision: \"review_edit\",\n      personalization_instruction: \"Keep the offer note concise.\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:read","applications:write","applications:transition_status","applications:offer","communications:read","communications:write"]}],"responses":{"202":{"description":"Approval preview created; no application, status, email, audit, or event mutation occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusEmailApprovalPocPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"current_status":{"type":"string","minLength":1},"target_status":{"type":"string","minLength":1},"email_type":{"type":"string","minLength":1},"decision":{"type":"string","minLength":1},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true},"personalization_instruction":{"type":"string","maxLength":2000,"nullable":true},"mode":{"type":"string","enum":["live","test"]}},"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/status_email_approval_poc/bind":{"post":{"operationId":"createApplicationsApplication_idActionsStatus_email_approval_pocBind","summary":"Bind status email approval POC","description":"Bind status email approval POC\n\n**Required scopes:** `applications:read`, `applications:write`, `applications:transition_status`, `applications:offer`, `communications:read`, `communications:write`\n\nApplications-owned POC preview→bind flow. This action is intentionally fixed to one explicit application, `Interviewing -> Offer`, `email_type=offer`, and `decision=review_edit`; unsupported transitions, decisions, send_now, natural-language targeting, bulk workflows, and autonomous sensitive sends are refused. Preview is mutation-free and returns the status side effect, reviewed-draft email side effect, sender/recipient/template provenance, approval binding fields, idempotency key, audit/event plan, and dashboard/API read-back hints. Bind requires the same Idempotency-Key as `binding.approved_idempotency_key`, verifies preview/input hashes and the resource version precondition, then records one status transition and one candidate email decision intent/draft effect. Events and evidence are redacted and do not expose provider secrets, OAuth tokens, raw provider payloads, raw prompt scaffolding, or candidate email addresses in API event payloads.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/status_email_approval_poc/bind \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: status-email-poc-preview-1' \\\n  -d '{\"current_status\":\"Interviewing\",\"target_status\":\"Offer\",\"email_type\":\"offer\",\"decision\":\"review_edit\",\"personalization_instruction\":\"Keep the offer note concise.\",\"binding\":{\"preview_hash\":\"...\",\"approved_action_key\":\"application.status_email_approval_poc\",\"approved_input_hash\":\"...\",\"approved_idempotency_key\":\"status-email-poc-preview-1\",\"resource_version_precondition\":\"updated_at:...\"}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/actions/status_email_approval_poc/bind\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": \"status-email-poc-preview-1\",\n    },\n    body: JSON.stringify({\n      current_status: \"Interviewing\",\n      target_status: \"Offer\",\n      email_type: \"offer\",\n      decision: \"review_edit\",\n      personalization_instruction: \"Keep the offer note concise.\",\n      binding: {\n        preview_hash: \"...\",\n        approved_action_key: \"application.status_email_approval_poc\",\n        approved_input_hash: \"...\",\n        approved_idempotency_key: \"status-email-poc-preview-1\",\n        resource_version_precondition: \"updated_at:...\",\n      },\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:read","applications:write","applications:transition_status","applications:offer","communications:read","communications:write"]}],"responses":{"200":{"description":"Bind succeeded or replayed; read `reused` and `status_transition.idempotent` to distinguish replay.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusEmailApprovalPocBind"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"current_status":{"type":"string","enum":["Interviewing"]},"target_status":{"type":"string","enum":["Offer"]},"email_type":{"type":"string","enum":["offer"]},"decision":{"type":"string","enum":["review_edit"]},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true},"personalization_instruction":{"type":"string","maxLength":2000,"nullable":true},"mode":{"type":"string","enum":["live","test"]},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["current_status","target_status","email_type","decision","binding"],"additionalProperties":false}}}}}},"/v1/applications/{application_id}/actions/archive":{"post":{"operationId":"createApplicationsApplication_idActionsArchive","summary":"Archive an application (preview→bind)","description":"Archive an application (preview→bind)\n\n**Required scopes:** `applications:write`, `applications:archive`\n\nPreview→bind flow. Calling without a `binding` returns HTTP 202 with the approval-required envelope (no mutation). To execute, re-issue with `binding` echoing the preview's `preview_hash`, `approved_action_key`, `approved_input_hash`, `approved_idempotency_key`, and `resource_version_precondition`. The `Idempotency-Key` must match between calls. Preview responses are not cached; bind responses are cached so retrying the bind under the same Idempotency-Key replays the original result without re-executing the mutation.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/actions/archive \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/actions/archive\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({}),\n  },\n).then((r) => r.json());\n```","tags":["Applications"],"deprecated":false,"security":[{"bearerAuth":["applications:write","applications:archive"]}],"responses":{"200":{"description":"Bind succeeded — application archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Application"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":2000},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"additionalProperties":false}}}}}},"/v1/email/drafts":{"get":{"operationId":"listEmailDrafts","summary":"GET /v1/email/drafts","description":"GET /v1/email/drafts\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraftListResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Repeatable or comma-separated. Restricts results to matching draft statuses.","schema":{"type":"string","enum":["pending_review","approved","send_reserved","sent","discarded","not_delivered","delivery_unconfirmed"]}},{"name":"email_type","in":"query","required":false,"description":"Repeatable or comma-separated. Restricts results to matching candidate email types.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/drafts/{id}":{"get":{"operationId":"retrieveEmailDraftsId","summary":"GET /v1/email/drafts/{id}","description":"GET /v1/email/drafts/{id}\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraft"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateEmailDraftsId","summary":"PATCH /v1/email/drafts/{id}","description":"PATCH /v1/email/drafts/{id}\n\n**Required scopes:** `communications:send`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:send"]}],"responses":{"200":{"description":"Draft saved.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraft"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject":{"type":"string","minLength":1},"html_body":{"type":"string","minLength":1},"text_body":{"type":"string","nullable":true},"from_name":{"type":"string","nullable":true},"reply_to":{"type":"string","nullable":true},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false}}}}}},"/v1/email/drafts/{id}/preview":{"get":{"operationId":"listEmailDraftsIdPreview","summary":"GET /v1/email/drafts/{id}/preview","description":"GET /v1/email/drafts/{id}/preview\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraftPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/drafts/{id}/history":{"get":{"operationId":"listEmailDraftsIdHistory","summary":"GET /v1/email/drafts/{id}/history","description":"GET /v1/email/drafts/{id}/history\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraftHistory"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/drafts/{id}/send":{"post":{"operationId":"createEmailDraftsIdSend","summary":"POST /v1/email/drafts/{id}/send","description":"POST /v1/email/drafts/{id}/send\n\n**Required scopes:** `communications:send`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:send"]}],"responses":{"200":{"description":"Draft sent.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraft"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reclaim_not_delivered":{"type":"boolean"}},"additionalProperties":false}}}}}},"/v1/email/drafts/{id}/discard":{"post":{"operationId":"createEmailDraftsIdDiscard","summary":"POST /v1/email/drafts/{id}/discard","description":"POST /v1/email/drafts/{id}/discard\n\n**Required scopes:** `communications:send`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:send"]}],"responses":{"200":{"description":"Draft discarded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailDraft"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/automation-settings":{"get":{"operationId":"listEmailAutomation-settings","summary":"GET /v1/email/automation-settings","description":"GET /v1/email/automation-settings\n\n**Required scopes:** `communications:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateEmailAutomation-settings","summary":"PATCH /v1/email/automation-settings","description":"PATCH /v1/email/automation-settings\n\n**Required scopes:** `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"auto_send_acknowledgment":{"type":"boolean"},"auto_send_advancement":{"type":"boolean"},"auto_send_interview_confirmation":{"type":"boolean"},"auto_send_rejection":{"type":"boolean"},"auto_send_offer":{"type":"boolean"},"candidate_sender_name":{"type":"string","minLength":1,"maxLength":120,"nullable":true},"candidate_reply_to_email":{"type":"string","format":"email","nullable":true},"quiet_hours_start":{"type":"integer","minimum":0,"maximum":23},"quiet_hours_end":{"type":"integer","minimum":0,"maximum":23}},"additionalProperties":false}}}}}},"/v1/email/sender-settings":{"get":{"operationId":"listEmailSender-settings","summary":"GET /v1/email/sender-settings","description":"GET /v1/email/sender-settings\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailSenderSettings"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/sender-connections":{"get":{"operationId":"listEmailSender-connections","summary":"GET /v1/email/sender-connections","description":"GET /v1/email/sender-connections\n\n**Required scopes:** `communications:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/sender-connections/actions/prepare_oauth":{"post":{"operationId":"createEmailSender-connectionsActionsPrepare_oauth","summary":"POST /v1/email/sender-connections/actions/prepare_oauth","description":"POST /v1/email/sender-connections/actions/prepare_oauth\n\n**Required scopes:** `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"provider":{"type":"string","enum":["google","microsoft"]},"redirect_uri":{"type":"string","format":"uri"},"return_to":{"type":"string","format":"uri","nullable":true},"connection_id":{"type":"string","format":"uuid"}},"required":["provider"],"additionalProperties":false}}}}}},"/v1/email/sender-connections/{provider_connection_id}/actions/refresh_discovery":{"post":{"operationId":"createEmailSender-connectionsProvider_connection_idActionsRefresh_discovery","summary":"POST /v1/email/sender-connections/{provider_connection_id}/actions/refresh_discovery","description":"POST /v1/email/sender-connections/{provider_connection_id}/actions/refresh_discovery\n\n**Required scopes:** `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/sender-connections/{provider_connection_id}/actions/disconnect":{"post":{"operationId":"createEmailSender-connectionsProvider_connection_idActionsDisconnect","summary":"POST /v1/email/sender-connections/{provider_connection_id}/actions/disconnect","description":"POST /v1/email/sender-connections/{provider_connection_id}/actions/disconnect\n\n**Required scopes:** `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/sender-defaults":{"get":{"operationId":"listEmailSender-defaults","summary":"GET /v1/email/sender-defaults","description":"GET /v1/email/sender-defaults\n\n**Required scopes:** `communications:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createEmailSender-defaults","summary":"POST /v1/email/sender-defaults","description":"POST /v1/email/sender-defaults\n\n**Required scopes:** `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","scorecard_nudge","scorecard_escalation","decision_brief","prospect_outreach","candidate_follow_up","interview_cancellation"]},"default_sender_type":{"type":"string","enum":["org_shared","owner","job_hiring_manager"]},"org_shared_sender_identity_id":{"type":"string","format":"uuid","nullable":true}},"required":["email_type","default_sender_type"],"additionalProperties":false}}}}}},"/v1/integrations/workspace/health":{"get":{"operationId":"listIntegrationsWorkspaceHealth","summary":"GET /v1/integrations/workspace/health","description":"GET /v1/integrations/workspace/health\n\n**Required scopes:** `communications:read`, `scheduling:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["communications:read","scheduling:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates":{"get":{"operationId":"listEmailTemplates","summary":"GET /v1/email/templates","description":"GET /v1/email/templates\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplatePolicy"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates/{email_type}":{"get":{"operationId":"retrieveEmailTemplatesEmail_type","summary":"GET /v1/email/templates/{email_type}","description":"GET /v1/email/templates/{email_type}\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateDetail"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates/{email_type}/actions/preview":{"post":{"operationId":"createEmailTemplatesEmail_typeActionsPreview","summary":"POST /v1/email/templates/{email_type}/actions/preview","description":"POST /v1/email/templates/{email_type}/actions/preview\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates/{email_type}/actions/validate":{"post":{"operationId":"createEmailTemplatesEmail_typeActionsValidate","summary":"POST /v1/email/templates/{email_type}/actions/validate","description":"POST /v1/email/templates/{email_type}/actions/validate\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateValidation"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_template":{"type":"string","minLength":1,"maxLength":1000},"html_body_template":{"type":"string","minLength":1,"maxLength":20000},"text_body_template":{"type":"string","minLength":1,"maxLength":20000}},"required":["subject_template","html_body_template","text_body_template"],"additionalProperties":false}}}}}},"/v1/email/templates/{email_type}/actions/publish":{"post":{"operationId":"createEmailTemplatesEmail_typeActionsPublish","summary":"POST /v1/email/templates/{email_type}/actions/publish","description":"POST /v1/email/templates/{email_type}/actions/publish\n\n**Required scopes:** `communications:write`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplatePublishResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"operation":{"type":"string","enum":["create","update","duplicate","reset","delete"],"default":"update"},"name":{"type":"string","minLength":1,"maxLength":200},"audience":{"type":"string","enum":["candidate","internal"]},"new_template_key":{"type":"string","pattern":"^[a-z][a-z0-9_]{0,99}$"},"subject_template":{"type":"string","minLength":1,"maxLength":1000},"html_body_template":{"type":"string","minLength":1,"maxLength":20000},"text_body_template":{"type":"string","minLength":1,"maxLength":20000},"version_label":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}}}},"/v1/email/templates/{email_type}/versions":{"get":{"operationId":"listEmailTemplatesEmail_typeVersions","summary":"GET /v1/email/templates/{email_type}/versions","description":"GET /v1/email/templates/{email_type}/versions\n\n**Required scopes:** `communications:read`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/EmailTemplateVersion"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates/{email_type}/versions/{version_id}/actions/rollback":{"post":{"operationId":"createEmailTemplatesEmail_typeVersionsVersion_idActionsRollback","summary":"POST /v1/email/templates/{email_type}/versions/{version_id}/actions/rollback","description":"POST /v1/email/templates/{email_type}/versions/{version_id}/actions/rollback\n\n**Required scopes:** `communications:write`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateRollbackResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"version_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/email/templates/{email_type}/actions/preview_customization":{"post":{"operationId":"createEmailTemplatesEmail_typeActionsPreview_customization","summary":"POST /v1/email/templates/{email_type}/actions/preview_customization","description":"POST /v1/email/templates/{email_type}/actions/preview_customization\n\n**Required scopes:** `communications:write`","tags":["Communications"],"deprecated":false,"security":[{"bearerAuth":["communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailTemplateCustomizationPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"email_type","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sample_instruction":{"type":"string","minLength":1,"maxLength":2000}},"required":["sample_instruction"],"additionalProperties":false}}}}}},"/v1/applications/{application_id}/email-decision/preview":{"post":{"operationId":"createApplicationsApplication_idEmail-decisionPreview","summary":"Preview a candidate status-change email decision","description":"Preview a candidate status-change email decision\n\n**Required scopes:** `applications:read`, `communications:read`\n\nSecret keys only. Previews the dashboard-visible candidate email decision states for a status transition without mutating the Application or drafts. Returns decision vocabulary, sender override validation, personalization tier, safety state, and side-effect preview.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_abc123/email-decision/preview \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"status\":\"Interviewing\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/applications/app_abc123/email-decision/preview\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ status: \"Interviewing\" }),\n}).then((r) => r.json());\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["applications:read","communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Applied","Scheduling","Screening","Interviewing","Offer","Hired","Offer Rejected","Disqualified","Withdrawn","On Hold"]},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true}},"required":["status"],"additionalProperties":false}}}}}},"/v1/applications/{application_id}/email-decision/apply":{"post":{"operationId":"createApplicationsApplication_idEmail-decisionApply","summary":"Apply a candidate status-change email decision","description":"Apply a candidate status-change email decision\n\n**Required scopes:** `applications:write`, `applications:transition_status`, `communications:write`\n\nSecret keys only. Applies the Application status transition and records the candidate email decision intent. Use `Idempotency-Key` for retries; replaying the same key with the same decision returns the prior result. `send_now` additionally requires `communications:send` and is rejected for approval-required communications.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_abc123/email-decision/apply \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"status\":\"Interviewing\",\"decision\":\"review_edit\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/applications/app_abc123/email-decision/apply\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({ status: \"Interviewing\", decision: \"review_edit\" }),\n}).then((r) => r.json());\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["applications:write","applications:transition_status","communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","enum":["Applied","Scheduling","Screening","Interviewing","Offer","Hired","Offer Rejected","Disqualified","Withdrawn","On Hold"]},"decision":{"type":"string","enum":["send_now","review_edit","dont_send"]},"personalization_instruction":{"type":"string","maxLength":2000,"nullable":true},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true},"batch_id":{"type":"string","format":"uuid","nullable":true},"is_bulk":{"type":"boolean"}},"required":["status","decision"],"additionalProperties":false}}}}}},"/v1/opportunities":{"get":{"operationId":"listOpportunities","summary":"List opportunities","description":"List opportunities\n\n**Required scopes:** `opportunities:read`\n\nRead-only. Opportunities are enriched candidate and interview-cycle work views over applications and related context. Use them for queues, next actions, and dashboard handoff; do not use this resource to create candidates or mutate application state.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/opportunities?status=Applied&limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/opportunities?status=Applied&limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Opportunities"],"deprecated":false,"security":[{"bearerAuth":["opportunities:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Opportunity"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by application status.","schema":{"type":"string"}},{"name":"stage","in":"query","required":false,"description":"Filter by application stage.","schema":{"type":"string"}},{"name":"person_id","in":"query","required":false,"description":"Filter by canonical `per_...` person id.","schema":{"type":"string"}},{"name":"application_id","in":"query","required":false,"description":"Filter by canonical `app_...` application id.","schema":{"type":"string"}},{"name":"job_posting_id","in":"query","required":false,"description":"Filter by existing `jp_...` posting id.","schema":{"type":"string"}},{"name":"created[gte]","in":"query","required":false,"description":"ISO-8601 UTC; only opportunities at or after this time.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","required":false,"description":"ISO-8601 UTC; only opportunities at or before this time.","schema":{"type":"string","format":"date-time"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/opportunities/{opportunity_id}":{"get":{"operationId":"retrieveOpportunitiesOpportunity_id","summary":"Retrieve an opportunity","description":"Retrieve an opportunity\n\n**Required scopes:** `opportunities:read`\n\nRead-only. The opportunity is the candidate/interview-cycle work view for an application; candidate creation and application-owned writes happen through People plus Applications.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/opportunities/opp_def456 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/opportunities/opp_def456\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Opportunities"],"deprecated":false,"security":[{"bearerAuth":["opportunities:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Opportunity"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"opportunity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/opportunities/{opportunity_id}/actions/next_action":{"get":{"operationId":"listOpportunitiesOpportunity_idActionsNext_action","summary":"Recommend the next action for an opportunity","description":"Recommend the next action for an opportunity\n\n**Required scopes:** `opportunities:read`, `tasks:read`\n\nComputes a recommendation envelope from the application's current status and any open `user_tasks` rows. Returns `{ recommended_action_key, target_status, rationale, requires_approval, can_complete_via_api, cannot_complete_reason }`. When the application is in a terminal status (`Hired`, `Withdrawn`, `Offer Rejected`, `Disqualified`), all action fields are `null` and `cannot_complete_reason` is `TASK_TERMINAL`. Other `cannot_complete_reason` values are `NO_REGISTRY_ACTION` and `OWNED_BY_LATER_API_CHILD` (see `docs/api/tasks-api.md`). Requires both `opportunities:read` and `tasks:read` because the recommendation reads from `user_tasks` on the application's behalf.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/opportunities/opp_def456/actions/next_action \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/opportunities/opp_def456/actions/next_action\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Opportunities"],"deprecated":false,"security":[{"bearerAuth":["opportunities:read","tasks:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"opportunity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/opportunities/{opportunity_id}/actions/deep_link":{"get":{"operationId":"listOpportunitiesOpportunity_idActionsDeep_link","summary":"Resolve an opportunity to a dashboard deep link","description":"Resolve an opportunity to a dashboard deep link\n\n**Required scopes:** `opportunities:read`\n\nReturns `{ id, web_url, route, mode }` pointing at the dashboard `OpportunityDetailPage` for candidate/interview-cycle workflow. Opportunity dashboard URLs use `/opportunities/:id`; during the current compatibility window, `:id` may be the `opp_…` display id exposed by list/read responses or the raw application UUID returned by this deep-link endpoint. Application Review detail links use `/jobs/:jobId/review/:applicationId`. Mode-partitioned: a live token requesting a test opportunity returns `404 not_found`.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/opportunities/opp_def456/actions/deep_link \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/opportunities/opp_def456/actions/deep_link\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Opportunities"],"deprecated":false,"security":[{"bearerAuth":["opportunities:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"opportunity_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/talent/search":{"get":{"operationId":"listTalentSearch","summary":"GET /v1/talent/search","description":"GET /v1/talent/search\n\n**Required scopes:** `applications:read`, `prospects:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["applications:read","prospects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/prospects":{"get":{"operationId":"listProspects","summary":"GET /v1/prospects","description":"GET /v1/prospects\n\n**Required scopes:** `prospects:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createProspects","summary":"Create a prospect","description":"Create a prospect\n\n**Required scopes:** `prospects:write`\n\nCreates CRM relationship state for an existing Person; it never creates the Person. If `person_id` is unavailable in the caller's organization and live/test partition, the response is 404 `person_not_found` with `param: person_id`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/prospects \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"person_id\":\"per_abc123\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/prospects\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ person_id: \"per_abc123\" }),\n});\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string"},"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"The teammate who owns this prospect. Omit the field and the prospect is owned by the human whose API key you are using; send `null` to leave it unowned. The user must be an active member of this organization, or the request is refused with `400 invalid_request_body`. Creating a prospect with an owner records the transition but creates no handoff task. Changing an existing prospect's owner separately creates a handoff task for the new owner unless it is an unassignment, self-assignment, or the owner has no resolvable email. Once a `next_follow_up_at` is set, the owner gets a distinct “Follow up with …” task; a prospect created here and left unowned has nobody to receive that task."},"owner_handoff_note":{"type":"string","maxLength":4000,"nullable":true,"description":"An optional note stored with the permanent owner-change timeline entry. On create, it requires a non-null owner; creating the prospect still does not mint a handoff task."},"source_label":{"type":"string","maxLength":200,"nullable":true},"last_contacted_at":{"type":"string","nullable":true},"last_reviewed_at":{"type":"string","nullable":true}},"required":["person_id"],"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}":{"get":{"operationId":"retrieveProspectsProspect_id","summary":"GET /v1/prospects/{prospect_id}","description":"GET /v1/prospects/{prospect_id}\n\n**Required scopes:** `prospects:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateProspectsProspect_id","summary":"PATCH /v1/prospects/{prospect_id}","description":"PATCH /v1/prospects/{prospect_id}\n\n**Required scopes:** `prospects:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"owner_user_id":{"type":"string","format":"uuid","nullable":true,"description":"Hand the prospect to another active member of this organization, or send `null` to leave it unowned. Omitting the field leaves the current owner exactly as it is — update never falls back to the key holder. A user who is not an active member of this organization is refused with `400 invalid_request_body`. Changing the owner creates a handoff task in its own right, independently of `next_follow_up_at`, unless it is an unassignment, self-assignment, or the owner has no resolvable email. While a follow-up date is set, the separate “Follow up with …” task also moves to the new owner."},"owner_handoff_note":{"type":"string","maxLength":4000,"nullable":true,"description":"An optional note stored with the permanent owner-change timeline entry and shown with the recipient's handoff task when one is created. This field must accompany owner_user_id, including `null` for a documented unassignment."},"relationship_status":{"type":"string","enum":["active","archived"]},"source_label":{"type":"string","maxLength":200,"nullable":true},"last_contacted_at":{"type":"string","nullable":true},"last_reviewed_at":{"type":"string","nullable":true},"next_follow_up_at":{"type":"string","nullable":true},"next_follow_up_note":{"type":"string","maxLength":500,"nullable":true},"archived_reason":{"type":"string","maxLength":500,"nullable":true}},"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}/activities":{"get":{"operationId":"listProspectsProspect_idActivities","summary":"GET /v1/prospects/{prospect_id}/activities","description":"GET /v1/prospects/{prospect_id}/activities\n\n**Required scopes:** `prospects:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createProspectsProspect_idActivities","summary":"POST /v1/prospects/{prospect_id}/activities","description":"POST /v1/prospects/{prospect_id}/activities\n\n**Required scopes:** `prospects:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"activity_type":{"type":"string","enum":["note","call","meeting","source","status_change"],"default":"note"},"body":{"type":"string","maxLength":4000,"nullable":true},"source_label":{"type":"string","maxLength":200,"nullable":true},"metadata":{"type":"object","additionalProperties":{}},"occurred_at":{"type":"string"}},"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}/actions/convert_to_application/preview":{"post":{"operationId":"createProspectsProspect_idActionsConvert_to_applicationPreview","summary":"Preview prospect conversion to an application","description":"Preview prospect conversion to an application\n\n**Required scopes:** `prospects:read`, `prospects:write`, `applications:write`\n\nPreviews conversion without writing. An unavailable Prospect returns 404 `prospect_not_found` with `param: prospect_id`; an unavailable target Job Posting returns 404 `job_posting_not_found` with `param: job_posting_id`. Use a fresh `Idempotency-Key` after resolving blockers.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/prospects/pro_abc123/actions/convert_to_application/preview \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"job_posting_id\":\"jp_xyz789\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/prospects/pro_abc123/actions/convert_to_application/preview\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({ job_posting_id: \"jp_xyz789\" }),\n});\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","prospects:write","applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_posting_id":{"type":"string","minLength":1},"source_label":{"type":"string","maxLength":200,"nullable":true},"note":{"type":"string","maxLength":2000,"nullable":true}},"required":["job_posting_id"],"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}/actions/convert_to_application/bind":{"post":{"operationId":"createProspectsProspect_idActionsConvert_to_applicationBind","summary":"Bind an approved prospect conversion","description":"Bind an approved prospect conversion\n\n**Required scopes:** `prospects:read`, `prospects:write`, `applications:write`\n\nBinds the approved conversion. An unavailable Prospect returns 404 `prospect_not_found` with `param: prospect_id`; an unavailable target Job Posting returns 404 `job_posting_not_found` with `param: job_posting_id`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/prospects/pro_abc123/actions/convert_to_application/bind \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"job_posting_id\":\"jp_xyz789\",\"binding\":{\"preview_hash\":\"…\",\"approved_action_key\":\"prospect.convert_to_application\",\"approved_input_hash\":\"…\",\"approved_idempotency_key\":\"7c3a…\",\"resource_version_precondition\":\"2026-08-18T00:00:00.000Z\"}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/prospects/pro_abc123/actions/convert_to_application/bind\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": \"7c3a…\",\n  },\n  body: JSON.stringify({\n    job_posting_id: \"jp_xyz789\",\n    binding: {\n      preview_hash: \"…\",\n      approved_action_key: \"prospect.convert_to_application\",\n      approved_input_hash: \"…\",\n      approved_idempotency_key: \"7c3a…\",\n      resource_version_precondition: \"2026-08-18T00:00:00.000Z\",\n    },\n  }),\n});\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","prospects:write","applications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_posting_id":{"type":"string","minLength":1},"source_label":{"type":"string","maxLength":200,"nullable":true},"note":{"type":"string","maxLength":2000,"nullable":true},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["job_posting_id","binding"],"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}/outreach/preview":{"post":{"operationId":"createProspectsProspect_idOutreachPreview","summary":"POST /v1/prospects/{prospect_id}/outreach/preview","description":"POST /v1/prospects/{prospect_id}/outreach/preview\n\n**Required scopes:** `prospects:read`, `communications:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","communications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_posting_id":{"type":"string","minLength":1,"nullable":true},"subject":{"type":"string","minLength":1,"maxLength":240,"nullable":true},"body":{"type":"string","minLength":1,"maxLength":8000,"nullable":true},"personalization_instruction":{"type":"string","maxLength":2000,"nullable":true},"outreach_intent_key":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"additionalProperties":false}}}}}},"/v1/prospects/{prospect_id}/outreach/drafts":{"post":{"operationId":"createProspectsProspect_idOutreachDrafts","summary":"POST /v1/prospects/{prospect_id}/outreach/drafts","description":"POST /v1/prospects/{prospect_id}/outreach/drafts\n\n**Required scopes:** `prospects:read`, `prospects:write`, `communications:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","prospects:write","communications:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_posting_id":{"type":"string","minLength":1,"nullable":true},"subject":{"type":"string","minLength":1,"maxLength":240,"nullable":true},"body":{"type":"string","minLength":1,"maxLength":8000,"nullable":true},"personalization_instruction":{"type":"string","maxLength":2000,"nullable":true},"outreach_intent_key":{"type":"string","minLength":1,"maxLength":120,"nullable":true}},"additionalProperties":false}}}}}},"/v1/prospect_imports/dry_run":{"post":{"operationId":"dryRunProspectImport","summary":"POST /v1/prospect_imports/dry_run","description":"POST /v1/prospect_imports/dry_run\n\n**Required scopes:** `prospects:read`, `prospects:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","prospects:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_label":{"type":"string","maxLength":200,"nullable":true},"rows":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string","maxLength":200},"name":{"type":"string","maxLength":500,"nullable":true},"email":{"type":"string","format":"email","maxLength":320,"nullable":true},"phone":{"type":"string","maxLength":50,"nullable":true},"linkedin_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"profile_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"resume_url":{"type":"string","format":"uri","maxLength":2048,"nullable":true},"current_title":{"type":"string","maxLength":300,"nullable":true},"current_company":{"type":"string","maxLength":300,"nullable":true},"source_label":{"type":"string","maxLength":200,"nullable":true},"pool_ids":{"type":"array","items":{"type":"string","minLength":1},"maxItems":25},"pool_names":{"type":"array","items":{"type":"string","minLength":1,"maxLength":160},"maxItems":25},"owner_user_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"string","format":"email","maxLength":320}],"nullable":true,"description":"Who owns the prospect, as a UUID or teammate email. The three states are deliberate: omit the field to use the applying key's human for a newly created prospect, send `null` to leave a new prospect unowned, or send a UUID or email to name an owner. On a row that matches an existing prospect, omitted and `null` both preserve its current owner; only a UUID or email reassigns it. The value must resolve to exactly one active, non-sample member of this organization, or that row is invalid: an email matching more than one teammate carries owner_ambiguous, and anything else that fails to resolve carries owner_not_member. Assignments to another teammate are applied after the row import and create one accumulating handoff summary per teammate; unassignment, self-assignment, and an owner without a resolvable email create no summary task."},"notes":{"type":"string","maxLength":10000,"nullable":true},"last_contacted_at":{"type":"string","nullable":true}},"additionalProperties":false},"minItems":1,"maxItems":500},"metadata":{"type":"object","additionalProperties":{}}},"required":["rows"],"additionalProperties":false}}}}}},"/v1/prospect_imports/{import_id}":{"get":{"operationId":"getProspectImport","summary":"GET /v1/prospect_imports/{import_id}","description":"GET /v1/prospect_imports/{import_id}\n\n**Required scopes:** `prospects:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/prospect_imports/{import_id}/apply":{"post":{"operationId":"applyProspectImport","summary":"POST /v1/prospect_imports/{import_id}/apply","description":"POST /v1/prospect_imports/{import_id}/apply\n\n**Required scopes:** `prospects:read`, `prospects:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["prospects:read","prospects:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"decisions":{"type":"array","items":{"type":"object","properties":{"row_index":{"type":"integer","minimum":0,"maximum":499},"input_hash":{"type":"string","minLength":1},"decision":{"type":"string","enum":["create_new","link_existing","skip"]},"person_id":{"type":"string","minLength":1}},"required":["row_index","input_hash","decision"],"additionalProperties":false},"maxItems":500,"default":[]}},"required":["preview_hash"],"additionalProperties":false}}}}}},"/v1/source_links":{"get":{"operationId":"listSourceLinks","summary":"GET /v1/source_links","description":"GET /v1/source_links\n\n**Required scopes:** `source_links:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["source_links:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createSourceLink","summary":"POST /v1/source_links","description":"POST /v1/source_links\n\n**Required scopes:** `source_links:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["source_links:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_posting_id":{"type":"string","minLength":1},"source_label":{"type":"string","minLength":1,"maxLength":200},"referrer_name":{"type":"string","maxLength":500,"nullable":true},"description":{"type":"string","maxLength":2000,"nullable":true},"expires_at":{"type":"string","nullable":true}},"required":["job_posting_id","source_label"],"additionalProperties":false}}}}}},"/v1/source_links/{source_link_id}":{"get":{"operationId":"getSourceLink","summary":"GET /v1/source_links/{source_link_id}","description":"GET /v1/source_links/{source_link_id}\n\n**Required scopes:** `source_links:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["source_links:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/source_links/{source_link_id}/disable":{"post":{"operationId":"disableSourceLink","summary":"POST /v1/source_links/{source_link_id}/disable","description":"POST /v1/source_links/{source_link_id}/disable\n\n**Required scopes:** `source_links:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["source_links:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","maxLength":500,"nullable":true}},"additionalProperties":false}}}}}},"/v1/talent_pools":{"get":{"operationId":"listTalent_pools","summary":"GET /v1/talent_pools","description":"GET /v1/talent_pools\n\n**Required scopes:** `talent_pools:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 25).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"include_archived","in":"query","required":false,"description":"When `true`, archived pools are listed alongside the active ones. Defaults to `false`, which leaves archived pools out.","schema":{"type":"boolean"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createTalent_pools","summary":"POST /v1/talent_pools","description":"POST /v1/talent_pools\n\n**Required scopes:** `talent_pools:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","maxLength":1000,"nullable":true}},"required":["name"],"additionalProperties":false}}}}}},"/v1/talent_pools/{pool_id}":{"get":{"operationId":"retrieveTalent_poolsPool_id","summary":"GET /v1/talent_pools/{pool_id}","description":"GET /v1/talent_pools/{pool_id}\n\n**Required scopes:** `talent_pools:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateTalent_poolsPool_id","summary":"PATCH /v1/talent_pools/{pool_id}","description":"PATCH /v1/talent_pools/{pool_id}\n\n**Required scopes:** `talent_pools:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":160},"description":{"type":"string","maxLength":1000,"nullable":true},"archived":{"type":"boolean"},"archived_reason":{"type":"string","maxLength":500,"nullable":true}},"additionalProperties":false}}}}}},"/v1/talent_pools/{pool_id}/members":{"get":{"operationId":"listTalent_poolsPool_idMembers","summary":"GET /v1/talent_pools/{pool_id}/members","description":"GET /v1/talent_pools/{pool_id}/members\n\n**Required scopes:** `talent_pools:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createTalent_poolsPool_idMembers","summary":"POST /v1/talent_pools/{pool_id}/members","description":"POST /v1/talent_pools/{pool_id}/members\n\n**Required scopes:** `talent_pools:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"prospect_id":{"type":"string"}},"required":["prospect_id"],"additionalProperties":false}}}}}},"/v1/talent_pools/{pool_id}/members/{prospect_id}":{"delete":{"operationId":"deleteTalent_poolsPool_idMembersProspect_id","summary":"DELETE /v1/talent_pools/{pool_id}/members/{prospect_id}","description":"DELETE /v1/talent_pools/{pool_id}/members/{prospect_id}\n\n**Required scopes:** `talent_pools:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["talent_pools:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/ats_imports/dry_run":{"post":{"operationId":"createAtsImportDryRun","summary":"POST /v1/ats_imports/dry_run","description":"POST /v1/ats_imports/dry_run\n\n**Required scopes:** `ats_imports:read`, `ats_imports:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["ats_imports:read","ats_imports:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"source_kind":{"type":"string","enum":["csv"]},"source_label":{"type":"string","maxLength":200,"nullable":true},"candidates":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","maxLength":500,"nullable":true},"email":{"type":"string","maxLength":320,"nullable":true},"phone":{"type":"string","maxLength":50,"nullable":true},"linkedin_url":{"type":"string","maxLength":2048,"nullable":true},"current_title":{"type":"string","maxLength":300,"nullable":true},"current_company":{"type":"string","maxLength":300,"nullable":true},"notes":{"type":"string","maxLength":10000,"nullable":true}},"additionalProperties":false},"maxItems":1000},"jobs":{"type":"array","items":{"type":"object","properties":{"title":{"type":"string","maxLength":500,"nullable":true},"department":{"type":"string","maxLength":300,"nullable":true},"location":{"type":"string","maxLength":300,"nullable":true},"location_type":{"type":"string","maxLength":100,"nullable":true},"status":{"type":"string","maxLength":50,"nullable":true}},"additionalProperties":false},"maxItems":1000},"applications":{"type":"array","items":{"type":"object","properties":{"candidate_email":{"type":"string","maxLength":320,"nullable":true},"candidate_name":{"type":"string","maxLength":500,"nullable":true},"job_title":{"type":"string","maxLength":500,"nullable":true},"stage":{"type":"string","maxLength":300,"nullable":true},"employment_start_date":{"type":"string","maxLength":50,"nullable":true}},"additionalProperties":false},"maxItems":1000},"metadata":{"type":"object","additionalProperties":{}}},"required":["source_kind"],"additionalProperties":false},{"type":"object","properties":{"source_kind":{"type":"string","enum":["greenhouse"]},"source_label":{"type":"string","maxLength":200,"nullable":true},"session_id":{"type":"string","minLength":1},"metadata":{"type":"object","additionalProperties":{}}},"required":["source_kind","session_id"],"additionalProperties":false}]}}}}}},"/v1/ats_imports/archive_upload_sessions":{"post":{"operationId":"createAtsImportArchiveUploadSession","summary":"POST /v1/ats_imports/archive_upload_sessions","description":"POST /v1/ats_imports/archive_upload_sessions\n\n**Required scopes:** `ats_imports:read`, `ats_imports:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["ats_imports:read","ats_imports:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"file_name":{"type":"string","minLength":1,"maxLength":255},"size_bytes":{"type":"integer","minimum":1,"maximum":52428800},"content_type":{"type":"string","minLength":1,"maxLength":255}},"required":["file_name","size_bytes"],"additionalProperties":false}}}}}},"/v1/ats_imports/{import_id}":{"get":{"operationId":"getAtsImportBatch","summary":"GET /v1/ats_imports/{import_id}","description":"GET /v1/ats_imports/{import_id}\n\n**Required scopes:** `ats_imports:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["ats_imports:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/ats_imports/{import_id}/apply":{"post":{"operationId":"applyAtsImportBatch","summary":"POST /v1/ats_imports/{import_id}/apply","description":"POST /v1/ats_imports/{import_id}/apply\n\n**Required scopes:** `ats_imports:read`, `ats_imports:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["ats_imports:read","ats_imports:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1}},"required":["preview_hash"],"additionalProperties":false}}}}}},"/v1/reporting/search":{"get":{"operationId":"listReportingSearch","summary":"Search reporting","description":"Search reporting\n\n**Required scopes:** `reporting:read`\n\nRead-only bounded recruiting reporting. query_family must be one of the canonical V1 reporting families; window_start and window_end are required; mode comes from the API token and cannot be overridden by livemode. Exact job_id and job_posting_id scopes fail closed for legacy reporting families until exact scoped reporting aggregations are available; prospect_ops_summary can use exact Job or Job Posting context for deterministic Prospect CRM operations counts. role_label remains an exact legacy fallback for non-prospect families. Responses expose counts, data-gap labels, canonical display ids, and dashboard links, and never expose raw scorecard notes, interviewer notes, decision brief text, emails, source internals, ROI, diversity, predictive, retention, or post-hire metrics.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/reporting/search?query_family=role_health_attention&window_start=2026-05-01&window_end=2026-05-26&role_label=AI%20Content%20Manager' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/reporting/search?query_family=role_health_attention&window_start=2026-05-01&window_end=2026-05-26&role_label=AI%20Content%20Manager\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Reporting"],"deprecated":false,"security":[{"bearerAuth":["reporting:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReportingSearchResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"query_family","in":"query","required":true,"description":"Canonical V1 reporting family. Short aliases and natural language are not accepted on the HTTP route.","schema":{"type":"string","enum":["role_health_attention","funnel_snapshot_by_role","stale_opportunity_queue","missing_feedback_queue","candidate_pool_strength","source_signals"]}},{"name":"window_start","in":"query","required":true,"description":"Required ISO date or datetime window start.","schema":{"type":"string"}},{"name":"window_end","in":"query","required":true,"description":"Required ISO date or datetime window end.","schema":{"type":"string"}},{"name":"job_id","in":"query","required":false,"description":"Exact canonical `job_...` role scope. Mutually exclusive with job_posting_id and role_label.","schema":{"type":"string"}},{"name":"job_posting_id","in":"query","required":false,"description":"Exact canonical `jp_...` posting scope. Mutually exclusive with job_id and role_label.","schema":{"type":"string"}},{"name":"role_label","in":"query","required":false,"description":"Exact role-label fallback for legacy reporting rows without job or posting ids.","schema":{"type":"string"}},{"name":"include_links","in":"query","required":false,"description":"Set to false to omit dashboard/reporting links. Defaults to true.","schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"description":"Queue result cap for bounded reporting families.","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor for bounded queue families.","schema":{"type":"string"}},{"name":"statuses","in":"query","required":false,"description":"Comma-separated exact application status filters for queue-style families.","schema":{"type":"string"}},{"name":"stages","in":"query","required":false,"description":"Comma-separated exact stage filters for queue-style families.","schema":{"type":"string"}},{"name":"source_label","in":"query","required":false,"description":"Exact source label filter for source-signal reporting.","schema":{"type":"string"}},{"name":"score_band","in":"query","required":false,"description":"Exact score band filter for candidate-pool reporting.","schema":{"type":"string"}},{"name":"stale_days","in":"query","required":false,"description":"Minimum stale-days threshold for stale opportunity queues.","schema":{"type":"integer","minimum":0}},{"name":"minimum_sample_size","in":"query","required":false,"description":"Minimum sample size threshold for reporting families that expose warning bands.","schema":{"type":"integer","minimum":0}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/whoami":{"get":{"operationId":"listWhoami","summary":"Identify the calling token","description":"Identify the calling token\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/whoami \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/whoami\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Auth"],"deprecated":false,"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/events":{"get":{"operationId":"listEvents","summary":"List events","description":"List events\n\n**Required scopes:** `api_events:read`\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/events?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/events?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Events"],"deprecated":false,"security":[{"bearerAuth":["api_events:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Event"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"type","in":"query","required":false,"description":"Repeatable; restricts to events whose `type` is in the set (max 50).","schema":{"type":"string"}},{"name":"created[gte]","in":"query","required":false,"description":"ISO-8601 UTC; only events at or after this time.","schema":{"type":"string","format":"date-time"}},{"name":"created[lte]","in":"query","required":false,"description":"ISO-8601 UTC; only events at or before this time.","schema":{"type":"string","format":"date-time"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/audit_log":{"get":{"operationId":"listAudit_log","summary":"List audit log entries","description":"List audit log entries\n\n**Required scopes:** `audit_logs:read`\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/audit_log?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/audit_log?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Audit"],"deprecated":false,"security":[{"bearerAuth":["audit_logs:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AuditLogEntry"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_plans":{"get":{"operationId":"listInterview_plans","summary":"List interview plans","description":"List interview plans\n\n**Required scopes:** `interview_plans:read`\n\nRead-only. Returns published interview plans in the token organization, newest first, partitioned by the token live/test mode and filtered to what the caller may see under the department read boundary. Draft plans are not included here: list them with `GET /v1/interview_plan_drafts`. Pass `job_id` to return only the plans linked to one Job.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/interview_plans?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plans?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Interview Plans"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InterviewPlanRead"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"job_id","in":"query","required":false,"description":"Return only plans linked to this Job, as a `job_...` display id. A well-formed id that matches nothing returns an empty list; a malformed one returns 400.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_plan_drafts":{"get":{"operationId":"listInterview_plan_drafts","summary":"List interview plan drafts","description":"List interview plan drafts\n\n**Required scopes:** `interview_plans:read`\n\nRead-only. Returns in-progress builder drafts in the token organization, newest first, partitioned by the token live/test mode. Drafts are organization-scoped and are deliberately NOT department-scoped: they carry no department, so every reader in the organization sees all of them. Pass `job_id` to return only the drafts seeded from one Source Job.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/interview_plan_drafts?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/InterviewPlanDraftRead"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"job_id","in":"query","required":false,"description":"Return only drafts linked to this Job, as a `job_...` display id. A well-formed id that matches nothing returns an empty list; a malformed one returns 400.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_plans/{interview_plan_id}":{"get":{"operationId":"retrieveInterview_plansInterview_plan_id","summary":"Retrieve an interview plan","description":"Retrieve an interview plan\n\n**Required scopes:** `interview_plans:read`\n\nRead-only. Returns the published or draft plan shape visible to the caller. Published plans are org-scoped role templates: live- and test-mode tokens in the same organization may read them. Draft reads remain livemode-partitioned. Round scorecard criteria are included only from inline round data; the API does not join through `interview_versions` for plan reads. For a draft's complete builder state (all stage checkpoints, `stage_versions`, question ids), use `GET /v1/interview_plan_drafts/{draft_id}` instead.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/interview_plans/ipd_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plans/ipd_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Interview Plans"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewPlanRead"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_plan_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_plan_drafts/{draft_id}":{"get":{"operationId":"retrieveInterview_plan_draftsDraft_id","summary":"Retrieve a draft's full content","description":"Retrieve a draft's full content\n\n**Required scopes:** `interview_plans:read`\n\nRead-only. Returns the draft's complete builder state: every stage checkpoint verbatim (outcomes, competencies, job_skills, interview_sequence, questions_and_directions), the per-stage `stage_versions` map, draft `status`, and a `source_metadata` provenance summary. This is the read half of the fetch-modify-submit editing loop: read the draft, take the edited stage's version from `stage_versions`, and pass it as the edit action's `source_stage` precondition. Questions always carry a discoverable id — stored ids verbatim, or a derived `question_N` fallback for generated questions that have not been edited yet.\n\nUse `GET /v1/interview_plans/{interview_plan_id}` for the narrow lifecycle-agnostic plan read; use this route when you need full draft content for editing or diffing. Cross-organization, wrong-mode, and unknown draft ids return safe not-found responses.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/interview_plan_drafts/ipd_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/ipd_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewPlanDraftRead"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"draft_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_plans/{interview_plan_id}/actions/archive":{"post":{"operationId":"createInterview_plansInterview_plan_idActionsArchive","summary":"POST /v1/interview_plans/{interview_plan_id}/actions/archive","description":"POST /v1/interview_plans/{interview_plan_id}/actions/archive\n\n**Required scopes:** `interview_plans:write`","tags":["Interview Plans"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Plan archived. The response is the plan read shape reflecting the archived state. An already-archived plan succeeds without a write. A plan still attached to a Job is refused with HTTP 409 `interview_plan_attached_to_job` — detach it from the Job first — including when it is already archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewPlanRead"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_plan_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/interview_plans/{interview_plan_id}/actions/unarchive":{"post":{"operationId":"createInterview_plansInterview_plan_idActionsUnarchive","summary":"POST /v1/interview_plans/{interview_plan_id}/actions/unarchive","description":"POST /v1/interview_plans/{interview_plan_id}/actions/unarchive\n\n**Required scopes:** `interview_plans:write`","tags":["Interview Plans"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Plan restored. The response is the plan read shape reflecting the live state. A plan that is already live succeeds without a write. If the plan still names a Job that has since acquired another live plan, the restore is refused with HTTP 409 naming the incumbent plan.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewPlanRead"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_plan_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_outcomes":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_outcomes","summary":"Generate draft outcomes","description":"Generate draft outcomes\n\n**Required scopes:** `interview_plans:write`\n\nWrites 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.\n\n**Seeding from a Source Job.** Pass `source_job_id` (a Job in the same organization, as its `job_<base32>` display id or its raw UUID) to seed the draft's `role_context` from the Job (title, description, group_id/department_label, location, location_type). Caller-provided `role_context` keys override the seeded values per-field; overriding the department emits a non-blocking `department_mismatch` warning in the response `warnings` array. Jobs outside the caller organization, and Jobs in a department the caller cannot read, return 404 `Source Job not found`. `source_job_id` cannot be combined with `resource.id` (returns 400) and is only accepted on `generate_outcomes`; later stages return 400.\n\n**Naming the plan.** `role_context.title` sets the plan title recruiters see in the app, and this is the only place a caller can set it — no later stage action, and no publish or modify_active input, accepts a title. Omit it and the plan falls back to a title derived from the role. It is distinct from `role_context.role_title`, which describes the role being hired for and feeds generation.\n\n**Example (seed-only):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_outcomes \\\\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\\\n  -H 'Content-Type: application/json' \\\\\n  -H 'Idempotency-Key: $(uuidgen)' \\\\\n  -d '{\"action\":\"interview_plan.generate_outcomes\",\"input\":{\"source_job_id\":\"00000000-0000-0000-0000-000000000123\",\"role_context\":{}}}'\n```\n\n**Example (seed + override):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_outcomes \\\\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\\\n  -H 'Content-Type: application/json' \\\\\n  -H 'Idempotency-Key: $(uuidgen)' \\\\\n  -d '{\"action\":\"interview_plan.generate_outcomes\",\"input\":{\"source_job_id\":\"00000000-0000-0000-0000-000000000123\",\"role_context\":{\"location\":\"Remote\"}}}'\n```\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_outcomes \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"action\":\"interview_plan.generate_outcomes\",\"input\":{\"role_context\":{\"role_title\":\"Account Executive\",\"title\":\"Account Executive — Enterprise\"}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_outcomes\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.generate_outcomes\",\n    input: {\n      role_context: {\n        role_title: \"Account Executive\",\n        title: \"Account Executive — Enterprise\",\n      },\n    },\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_outcomes"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"role_context":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"role_title":{"type":"string","minLength":1,"maxLength":300},"organization_context":{"type":"string","maxLength":10000},"additional_context":{"type":"string","maxLength":20000},"location":{"type":"string","maxLength":300},"location_type":{"type":"string","maxLength":100},"department":{"type":"string","maxLength":64},"department_label":{"type":"string","maxLength":200}},"additionalProperties":false},"instructions":{"type":"string","maxLength":10000},"accepted_outcomes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"text":{"type":"string","minLength":1,"maxLength":500},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","maxLength":128},"tag":{"type":"string","maxLength":128}},"additionalProperties":false},"minItems":1,"maxItems":25,"description":"Optional caller-supplied outcomes stored verbatim with no AI generation, mirroring accepted_skills/accepted_rounds. When provided, the outcomes checkpoint is written directly from this list — deterministic and LLM-free — so a draft can be bootstrapped without any generation call. Combines with source_job_id (role_context seeding is independent of generation)."},"source_job_id":{"type":"string","description":"Optional Source Job in the same organization, given as the `job_<base32>` display id or the raw UUID. When provided, the draft's role_context is seeded from the Job (title, description, group_id/department_label, location, location_type). Caller-provided role_context keys override the seeded values per-field. Organization and department enforced — a Source Job in another organization, or in a department the caller cannot read, returns 404 with no existence leak. Only accepted on generate_outcomes; passing source_job_id to later stages returns 400. Cannot be combined with resource.id (returns 400)."}},"required":["role_context"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/confirm_outcomes":{"post":{"operationId":"createInterview_plan_draftsActionsConfirm_outcomes","summary":"Confirm draft outcomes","description":"Confirm draft outcomes\n\n**Required scopes:** `interview_plans:write`\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/confirm_outcomes \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.confirm_outcomes\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"accepted_outcomes\":[{\"text\":\"Diagnose customer needs\"}]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/confirm_outcomes\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.confirm_outcomes\",\n    resource: { type: \"interview_plan_draft\", id: \"ipd_…\" },\n    input: { accepted_outcomes: [{ text: \"Diagnose customer needs\" }] },\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.confirm_outcomes"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"accepted_outcomes":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"text":{"type":"string","minLength":1,"maxLength":500},"title":{"type":"string","minLength":1,"maxLength":500},"description":{"type":"string","maxLength":5000},"priority":{"type":"string","maxLength":128},"tag":{"type":"string","maxLength":128}},"additionalProperties":false},"minItems":1,"maxItems":25},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["role_context","outcomes","competencies","skills","interview_sequence","questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"revision_notes":{"type":"string","maxLength":10000}},"required":["accepted_outcomes"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_competencies":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_competencies","summary":"Generate draft competencies","description":"Generate draft competencies\n\n**Required scopes:** `interview_plans:write`\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_competencies \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.generate_competencies\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_competencies\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.generate_competencies\",\n    resource: { type: \"interview_plan_draft\", id: \"ipd_…\" },\n    input: {},\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_competencies"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["outcomes"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"outcome_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"maxItems":50},"instructions":{"type":"string","maxLength":10000}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_skills":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_skills","summary":"Generate draft skills","description":"Generate draft skills\n\n**Required scopes:** `interview_plans:write`\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_skills \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.generate_skills\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_skills\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.generate_skills\",\n    resource: { type: \"interview_plan_draft\", id: \"ipd_…\" },\n    input: {},\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_skills"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"instructions":{"type":"string","maxLength":10000},"accepted_skills":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":300},"skill":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"details":{"type":"string","maxLength":5000},"requirement":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":128}},"additionalProperties":false},"minItems":1,"maxItems":50}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_rounds":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_rounds","summary":"Generate draft rounds","description":"Generate draft rounds\n\n**Required scopes:** `interview_plans:write`\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_rounds \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.generate_rounds\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/generate_rounds\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.generate_rounds\",\n    resource: { type: \"interview_plan_draft\", id: \"ipd_…\" },\n    input: {},\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_rounds"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["skills"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"instructions":{"type":"string","maxLength":10000},"accepted_rounds":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"title":{"type":"string","minLength":1,"maxLength":300},"name":{"type":"string","minLength":1,"maxLength":300},"round":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"purpose":{"type":"string","maxLength":5000},"duration":{"type":"integer","minimum":0,"maximum":480},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"primaryFocus":{"type":"string","maxLength":500},"questionTypes":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":50},"interviewerGuidance":{"type":"string","maxLength":5000},"recommendedQuestionCount":{"type":"integer","minimum":0,"maximum":100}},"additionalProperties":false},"minItems":1,"maxItems":20}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/add_rounds":{"post":{"operationId":"createInterview_plan_draftsActionsAdd_rounds","summary":"Add draft interview rounds verbatim","description":"Add draft interview rounds verbatim\n\n**Required scopes:** `interview_plans:write`\n\nAdds the supplied interview rounds to the draft exactly as written. Requires the skills checkpoint.\n\n**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_*`.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/add_rounds \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.add_rounds\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"items\":[{\"title\":\"Technical Deep Dive\",\"description\":\"Systems design and hands-on problem solving.\",\"duration\":60}]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/add_rounds\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.add_rounds\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"items\": [\n      {\n        \"title\": \"Technical Deep Dive\",\n        \"description\": \"Systems design and hands-on problem solving.\",\n        \"duration\": 60\n      }\n    ]\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.add_rounds"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"title":{"type":"string","minLength":1,"maxLength":300},"name":{"type":"string","minLength":1,"maxLength":300},"round":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"purpose":{"type":"string","maxLength":5000},"duration":{"type":"integer","minimum":0,"maximum":480},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"primaryFocus":{"type":"string","maxLength":500},"questionTypes":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":50},"interviewerGuidance":{"type":"string","maxLength":5000},"recommendedQuestionCount":{"type":"integer","minimum":0,"maximum":100}},"additionalProperties":false},"minItems":1,"maxItems":20},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["interview_sequence"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["items"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_rounds":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_rounds","summary":"Update or reorder draft interview rounds verbatim","description":"Update or reorder draft interview rounds verbatim\n\n**Required scopes:** `interview_plans:write`\n\nReplaces 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.\n\n**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.\n\n**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_*`.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_rounds \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -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}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_rounds\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_rounds\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"items\": [\n      {\n        \"id\": \"round_1\",\n        \"title\": \"Recruiter Screen\",\n        \"description\": \"Motivation, logistics, and mutual fit.\",\n        \"duration\": 30\n      }\n    ],\n    \"source_stage\": {\n      \"stage\": \"interview_sequence\",\n      \"version\": 4\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_rounds"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"title":{"type":"string","minLength":1,"maxLength":300},"name":{"type":"string","minLength":1,"maxLength":300},"round":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"purpose":{"type":"string","maxLength":5000},"duration":{"type":"integer","minimum":0,"maximum":480},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"primaryFocus":{"type":"string","maxLength":500},"questionTypes":{"type":"array","items":{"type":"string","maxLength":300},"maxItems":50},"interviewerGuidance":{"type":"string","maxLength":5000},"recommendedQuestionCount":{"type":"integer","minimum":0,"maximum":100}},"additionalProperties":false},"maxItems":20},"order":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":20},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["interview_sequence"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/delete_rounds":{"post":{"operationId":"createInterview_plan_draftsActionsDelete_rounds","summary":"Delete draft interview rounds and prune their questions","description":"Delete draft interview rounds and prune their questions\n\n**Required scopes:** `interview_plans:write`\n\n**Prune-and-report.** Deleting a round prunes its questions and directions from the `questions_and_directions` checkpoint in the same atomic write: the response reports `pruned_question_round_ids` and the `questions_and_directions` stage version bumps alongside `interview_sequence`. A follow-up questions or directions edit carrying the pre-prune version returns 409 `stale_source_stage`.\n\n**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_*`.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_rounds \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.delete_rounds\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"ids\":[\"round_3\"],\"source_stage\":{\"stage\":\"interview_sequence\",\"version\":4}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_rounds\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.delete_rounds\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"ids\": [\n      \"round_3\"\n    ],\n    \"source_stage\": {\n      \"stage\": \"interview_sequence\",\n      \"version\": 4\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.delete_rounds"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":20},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["interview_sequence"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["ids"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_anchors":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_anchors","summary":"POST /v1/interview_plan_drafts/actions/generate_anchors","description":"POST /v1/interview_plan_drafts/actions/generate_anchors\n\n**Required scopes:** `interview_plans:write`","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_anchors"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"competency_id":{"type":"string","minLength":1,"maxLength":128},"instructions":{"type":"string","maxLength":10000}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/generate_questions_directions":{"post":{"operationId":"createInterview_plan_draftsActionsGenerate_questions_directions","summary":"POST /v1/interview_plan_drafts/actions/generate_questions_directions","description":"POST /v1/interview_plan_drafts/actions/generate_questions_directions\n\n**Required scopes:** `interview_plans:write`","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.generate_questions_directions"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["interview_sequence"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"round_id":{"type":"string","minLength":1,"maxLength":128},"instructions":{"type":"string","maxLength":10000}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/add_competencies":{"post":{"operationId":"createInterview_plan_draftsActionsAdd_competencies","summary":"Add draft competencies verbatim","description":"Add draft competencies verbatim\n\n**Required scopes:** `interview_plans:write`\n\nAdds the supplied competencies to the draft exactly as written. Requires confirmed outcomes.\n\n**Count invariants.** The competencies stage must hold between 1 and 25 items after every edit: deleting the last item or adding past 25 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 25-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/add_competencies \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.add_competencies\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"items\":[{\"name\":\"Customer Empathy\",\"description\":\"Understands and advocates for customer needs.\"}]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/add_competencies\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.add_competencies\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"items\": [\n      {\n        \"name\": \"Customer Empathy\",\n        \"description\": \"Understands and advocates for customer needs.\"\n      }\n    ]\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.add_competencies"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":300},"competency":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":5000},"details":{"type":"string","minLength":1,"maxLength":5000},"definition":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false},"minItems":1,"maxItems":25},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["items"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_competencies":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_competencies","summary":"Update or reorder draft competencies verbatim","description":"Update or reorder draft competencies verbatim\n\n**Required scopes:** `interview_plans:write`\n\nReplaces competencies by id and/or reorders the stage. `order` must be a complete permutation of the resulting competency ids; pure reorder works with `order` alone. Provide items, order, or both.\n\n**Count invariants.** The competencies stage must hold between 1 and 25 items after every edit: deleting the last item or adding past 25 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 25-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_competencies \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.update_competencies\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"items\":[{\"id\":\"competency_1\",\"name\":\"Customer Empathy\",\"description\":\"Understands and advocates for customer needs.\"}],\"source_stage\":{\"stage\":\"competencies\",\"version\":3}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_competencies\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_competencies\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"items\": [\n      {\n        \"id\": \"competency_1\",\n        \"name\": \"Customer Empathy\",\n        \"description\": \"Understands and advocates for customer needs.\"\n      }\n    ],\n    \"source_stage\": {\n      \"stage\": \"competencies\",\n      \"version\": 3\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_competencies"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":300},"competency":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","minLength":1,"maxLength":5000},"details":{"type":"string","minLength":1,"maxLength":5000},"definition":{"type":"string","minLength":1,"maxLength":5000}},"additionalProperties":false},"maxItems":25},"order":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":25},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/delete_competencies":{"post":{"operationId":"createInterview_plan_draftsActionsDelete_competencies","summary":"Delete draft competencies and prune their anchors","description":"Delete draft competencies and prune their anchors\n\n**Required scopes:** `interview_plans:write`\n\n**Prune-and-report.** Deleting a competency prunes its behavioral-anchor entry in the same atomic write: the response reports `pruned_behavioral_anchor_ids` and the `questions_and_directions` stage version bumps alongside `competencies`. A follow-up anchor edit carrying the pre-prune `questions_and_directions` version returns 409 `stale_source_stage`.\n\n**Count invariants.** The competencies stage must hold between 1 and 25 items after every edit: deleting the last item or adding past 25 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 25-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_competencies \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.delete_competencies\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"ids\":[\"competency_2\"],\"source_stage\":{\"stage\":\"competencies\",\"version\":3}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_competencies\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.delete_competencies\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"ids\": [\n      \"competency_2\"\n    ],\n    \"source_stage\": {\n      \"stage\": \"competencies\",\n      \"version\": 3\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.delete_competencies"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":25},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["ids"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/add_skills":{"post":{"operationId":"createInterview_plan_draftsActionsAdd_skills","summary":"Add draft job skills verbatim","description":"Add draft job skills verbatim\n\n**Required scopes:** `interview_plans:write`\n\nAdds the supplied job skills to the draft exactly as written. Requires the competencies checkpoint.\n\n**Count invariants.** The job skills stage must hold between 1 and 50 items after every edit: deleting the last item or adding past 50 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 50-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/add_skills \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.add_skills\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"items\":[{\"name\":\"SQL\",\"description\":\"Writes and optimizes analytical queries.\"}]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/add_skills\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.add_skills\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"items\": [\n      {\n        \"name\": \"SQL\",\n        \"description\": \"Writes and optimizes analytical queries.\"\n      }\n    ]\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.add_skills"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":300},"skill":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"details":{"type":"string","maxLength":5000},"requirement":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":128}},"additionalProperties":false},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["skills"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["items"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_skills":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_skills","summary":"Update or reorder draft job skills verbatim","description":"Update or reorder draft job skills verbatim\n\n**Required scopes:** `interview_plans:write`\n\nReplaces job skills by id and/or reorders the stage. `order` must be a complete permutation of the resulting skill ids; pure reorder works with `order` alone. Provide items, order, or both.\n\n**Count invariants.** The job skills stage must hold between 1 and 50 items after every edit: deleting the last item or adding past 50 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 50-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_skills \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.update_skills\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"order\":[\"skill_2\",\"skill_1\"],\"source_stage\":{\"stage\":\"skills\",\"version\":2}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_skills\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_skills\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"order\": [\n      \"skill_2\",\n      \"skill_1\"\n    ],\n    \"source_stage\": {\n      \"stage\": \"skills\",\n      \"version\": 2\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_skills"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"name":{"type":"string","minLength":1,"maxLength":300},"title":{"type":"string","minLength":1,"maxLength":300},"skill":{"type":"string","minLength":1,"maxLength":300},"description":{"type":"string","maxLength":5000},"details":{"type":"string","maxLength":5000},"requirement":{"type":"string","maxLength":5000},"category":{"type":"string","maxLength":128}},"additionalProperties":false},"maxItems":50},"order":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["skills"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/delete_skills":{"post":{"operationId":"createInterview_plan_draftsActionsDelete_skills","summary":"Delete draft job skills","description":"Delete draft job skills\n\n**Required scopes:** `interview_plans:write`\n\nDeletes job skills by id. Skills have no dependent keyed data, so nothing is pruned.\n\n**Count invariants.** The job skills stage must hold between 1 and 50 items after every edit: deleting the last item or adding past 50 returns a validation error. Emptying the stage on purpose is the one exception, and it has its own verb — see `clear_*`.\n\n**Replacing a full stage.** When the stage is at its 50-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.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_skills \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.delete_skills\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"ids\":[\"skill_3\"],\"source_stage\":{\"stage\":\"skills\",\"version\":2}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_skills\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.delete_skills\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"ids\": [\n      \"skill_3\"\n    ],\n    \"source_stage\": {\n      \"stage\": \"skills\",\n      \"version\": 2\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.delete_skills"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["skills"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["ids"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/clear_outcomes":{"post":{"operationId":"createInterview_plan_draftsActionsClear_outcomes","summary":"Clear every draft outcome","description":"Clear every draft outcome\n\n**Required scopes:** `interview_plans:write`\n\nEmpties the outcomes stage. Nothing downstream is pruned — competencies, skills, rounds, and questions keep their content and their own versions.\n\n**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*.\n\n**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.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_outcomes \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.clear_outcomes\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"source_stage\":{\"stage\":\"outcomes\",\"version\":3}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_outcomes\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.clear_outcomes\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"source_stage\": {\n      \"stage\": \"outcomes\",\n      \"version\": 3\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.clear_outcomes"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["outcomes"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/clear_competencies":{"post":{"operationId":"createInterview_plan_draftsActionsClear_competencies","summary":"Clear every draft competency","description":"Clear every draft competency\n\n**Required scopes:** `interview_plans:write`\n\nEmpties the competencies stage. **Prune-and-report.** Every cleared competency's behavioral-anchor entry is pruned in the same atomic write: the response reports `pruned_behavioral_anchor_ids` and the `questions_and_directions` stage version bumps alongside `competencies`. A follow-up anchor edit carrying the pre-prune `questions_and_directions` version returns 409 `stale_source_stage`.\n\n**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*.\n\n**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.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_competencies \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.clear_competencies\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"source_stage\":{\"stage\":\"competencies\",\"version\":2}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_competencies\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.clear_competencies\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"source_stage\": {\n      \"stage\": \"competencies\",\n      \"version\": 2\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.clear_competencies"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["competencies"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/clear_job_skills":{"post":{"operationId":"createInterview_plan_draftsActionsClear_job_skills","summary":"Clear every draft job skill","description":"Clear every draft job skill\n\n**Required scopes:** `interview_plans:write`\n\nEmpties the job skills stage. Skills have no dependent keyed data, so nothing is pruned.\n\n**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*.\n\n**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.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_job_skills \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.clear_job_skills\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"source_stage\":{\"stage\":\"skills\",\"version\":2}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_job_skills\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.clear_job_skills\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"source_stage\": {\n      \"stage\": \"skills\",\n      \"version\": 2\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.clear_job_skills"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["skills"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/clear_interview_sequence":{"post":{"operationId":"createInterview_plan_draftsActionsClear_interview_sequence","summary":"Clear every draft interview round","description":"Clear every draft interview round\n\n**Required scopes:** `interview_plans:write`\n\nEmpties the interview sequence stage. **Prune-and-report.** Every cleared round's questions and directions are pruned in the same atomic write: the response reports `pruned_question_round_ids` and the `questions_and_directions` stage version bumps alongside `interview_sequence`.\n\n**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*.\n\n**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.\n\n**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.\n\n**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.\n\n**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`.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_interview_sequence \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.clear_interview_sequence\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"source_stage\":{\"stage\":\"interview_sequence\",\"version\":4}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/clear_interview_sequence\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.clear_interview_sequence\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"source_stage\": {\n      \"stage\": \"interview_sequence\",\n      \"version\": 4\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.clear_interview_sequence"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["interview_sequence"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/validate_draft":{"post":{"operationId":"createInterview_plan_draftsActionsValidate_draft","summary":"Validate draft interview plan","description":"Validate draft interview plan\n\n**Required scopes:** `interview_plans:write`\n\nValidation is read-only. It returns blockers, warnings, next actions, and the builder `web_url` deep link when the draft is known, but it does not create write audit/event rows.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/validate_draft \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.validate_draft\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"include_warnings\":true}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/validate_draft\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.validate_draft\",\n    resource: { type: \"interview_plan_draft\", id: \"ipd_…\" },\n    input: { include_warnings: true },\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.validate_draft"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"include_warnings":{"type":"boolean"}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plans/actions/publish":{"post":{"operationId":"createInterview_plansActionsPublish","summary":"Publish an interview plan (preview→bind)","description":"Publish an interview plan (preview→bind)\n\n**Required scopes:** `interview_plans:write`, `interview_plans:publish`\n\nPreview→bind flow. Calling without a `binding` returns HTTP 202 with the approval-required envelope (no mutation); the 200 response shape documented here is returned only on the bind call, which persists a new `interview_plans` row. To execute, re-issue with `binding` echoing the preview's `preview_hash`, `approved_action_key`, `approved_input_hash`, `approved_idempotency_key`, and `resource_version_precondition`. The key captured in `approval.binding.approved_idempotency_key` must match on the bind request.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plans/actions/publish \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"action\":\"interview_plan.publish\",\"input\":{\"draft_id\":\"ipd_…\"}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plans/actions/publish\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.publish\",\n    input: { draft_id: \"ipd_…\" },\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write","interview_plans:publish"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewPlan"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.publish"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"draft_id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"},"expected_draft_version":{"type":"integer","minimum":0},"approval_id":{"type":"string","maxLength":128}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plans/actions/modify_active":{"post":{"operationId":"createInterview_plansActionsModify_active","summary":"Modify an active interview plan (preview→bind)","description":"Modify an active interview plan (preview→bind)\n\n**Required scopes:** `interview_plans:write`, `interview_plans:modify_active`\n\nPreview→bind flow. Calling without a `binding` returns HTTP 202 with the approval-required envelope (no mutation), including the active plan's affected application and session counts and a redacted per-round reassignment plan. The 200 response shape documented here is returned only on the bind call, which applies the content the preview showed: it writes the plan columns the draft addressed — title, role name, additional info, location, location type, outcomes, competencies, job skills, behavioral anchors and the interview sequence — mints a new active `interview_versions` row per changed round, repoints `not_started` sessions to the new content, and keeps `in_progress`/`completed` sessions pinned to the prior content. A section the draft never addressed is left exactly as it is on the live plan. To execute, re-issue with `binding` echoing the preview's `preview_hash`, `approved_action_key`, `approved_input_hash`, `approved_idempotency_key`, and `resource_version_precondition`. The key captured in `approval.binding.approved_idempotency_key` must match on the bind request. The `resource_version_precondition` keys off the active plan's `updated_at`; a concurrent active-plan edit between preview and bind returns 409 `precondition_failed`.\n\n**Applying an emptied section.** A draft stage emptied with `clear_*` is applied here like any other change: the live plan's matching section is emptied too. This is the only way an emptied section reaches a live plan — a cleared draft cannot be published as a new plan, because draft validation still requires items. A section the draft never touched is still never written: emptying reaches the live plan only when the draft carries an explicit `clear_*` marker for that stage, which is what distinguishes a deliberate emptying from a section the editor simply left alone.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plans/actions/modify_active \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"action\":\"interview_plan.modify_active\",\"input\":{\"draft_id\":\"ipd_…\",\"active_plan_id\":\"plan_…\"}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plans/actions/modify_active\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({\n    action: \"interview_plan.modify_active\",\n    input: { draft_id: \"ipd_…\", active_plan_id: \"plan_…\" },\n  }),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write","interview_plans:modify_active"]}],"responses":{"200":{"description":"Bind succeeded — active plan modified.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModifyActiveResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.modify_active"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan"]},"id":{"type":"string","minLength":1,"maxLength":128}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"draft_id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"},"active_plan_id":{"type":"string","minLength":1,"maxLength":128},"expected_draft_version":{"type":"integer","minimum":0},"expected_plan_version":{"type":"integer","minimum":0},"approval_id":{"type":"string","maxLength":128}},"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/add_questions":{"post":{"operationId":"createInterview_plan_draftsActionsAdd_questions","summary":"Add questions to one draft round verbatim","description":"Add questions to one draft round verbatim\n\n**Required scopes:** `interview_plans:write`\n\nAppends caller-supplied questions to one round (`round_id`). Each round holds at most 50 questions.\n\n**Question ids.** Generated questions are stored without ids; the first edit touching a round's questions persists derived `question_N` ids for every question in that round in the same write. Read the draft first (`GET /v1/interview_plan_drafts/{draft_id}`) to discover the ids. An unknown `round_id` returns 404 `draft_item_not_found`.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/add_questions \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.add_questions\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"round_id\":\"round_1\",\"questions\":[{\"text\":\"Walk me through a time you changed a customer's mind.\",\"guidance\":\"Listen for evidence of discovery before persuasion.\"}]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/add_questions\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.add_questions\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"round_id\": \"round_1\",\n    \"questions\": [\n      {\n        \"text\": \"Walk me through a time you changed a customer's mind.\",\n        \"guidance\": \"Listen for evidence of discovery before persuasion.\"\n      }\n    ]\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.add_questions"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"round_id":{"type":"string","minLength":1,"maxLength":128},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"text":{"type":"string","minLength":1,"maxLength":5000},"guidance":{"type":"string","maxLength":10000},"followUpQuestions":{"type":"array","items":{"type":"string","maxLength":2000},"maxItems":20},"tags":{"type":"array","items":{"type":"string","maxLength":128},"maxItems":20}},"required":["text"],"additionalProperties":false},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["round_id","questions"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_questions":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_questions","summary":"Update or reorder one draft round's questions verbatim","description":"Update or reorder one draft round's questions verbatim\n\n**Required scopes:** `interview_plans:write`\n\nReplaces questions by id within one round and/or reorders them. `order` must be a complete permutation of that round's resulting question ids; pure reorder works with `order` alone.\n\n**Question ids.** Generated questions are stored without ids; the first edit touching a round's questions persists derived `question_N` ids for every question in that round in the same write. Read the draft first to discover the ids.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_questions \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.update_questions\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"round_id\":\"round_1\",\"questions\":[{\"id\":\"question_2\",\"text\":\"Tell me about a deal you lost and what you changed after.\"}],\"source_stage\":{\"stage\":\"questions_and_directions\",\"version\":5}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_questions\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_questions\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"round_id\": \"round_1\",\n    \"questions\": [\n      {\n        \"id\": \"question_2\",\n        \"text\": \"Tell me about a deal you lost and what you changed after.\"\n      }\n    ],\n    \"source_stage\": {\n      \"stage\": \"questions_and_directions\",\n      \"version\": 5\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_questions"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"round_id":{"type":"string","minLength":1,"maxLength":128},"questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","maxLength":128},"text":{"type":"string","minLength":1,"maxLength":5000},"guidance":{"type":"string","maxLength":10000},"followUpQuestions":{"type":"array","items":{"type":"string","maxLength":2000},"maxItems":20},"tags":{"type":"array","items":{"type":"string","maxLength":128},"maxItems":20}},"required":["text"],"additionalProperties":false},"maxItems":50},"order":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["round_id"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/delete_questions":{"post":{"operationId":"createInterview_plan_draftsActionsDelete_questions","summary":"Delete questions from one draft round","description":"Delete questions from one draft round\n\n**Required scopes:** `interview_plans:write`\n\nDeletes questions by id from one round. Unknown question or round ids return 404 `draft_item_not_found` naming the id.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_questions \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.delete_questions\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"round_id\":\"round_1\",\"ids\":[\"question_3\"],\"source_stage\":{\"stage\":\"questions_and_directions\",\"version\":5}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_questions\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.delete_questions\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"round_id\": \"round_1\",\n    \"ids\": [\n      \"question_3\"\n    ],\n    \"source_stage\": {\n      \"stage\": \"questions_and_directions\",\n      \"version\": 5\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.delete_questions"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":50},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false},"round_id":{"type":"string","minLength":1,"maxLength":128}},"required":["ids","round_id"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_round_directions":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_round_directions","summary":"Set one draft round's directions verbatim","description":"Set one draft round's directions verbatim\n\n**Required scopes:** `interview_plans:write`\n\nSets one round's interviewer and/or candidate directions exactly as written. Provide `interviewer_directions`, `candidate_directions`, or both; an omitted field is left unchanged.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_round_directions \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.update_round_directions\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"round_id\":\"round_1\",\"interviewer_directions\":\"Probe for structured discovery; score against the rubric, not rapport.\"}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_round_directions\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_round_directions\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"round_id\": \"round_1\",\n    \"interviewer_directions\": \"Probe for structured discovery; score against the rubric, not rapport.\"\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_round_directions"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"round_id":{"type":"string","minLength":1,"maxLength":128},"interviewer_directions":{"type":"string","maxLength":20000},"candidate_directions":{"type":"string","maxLength":20000},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["round_id"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/update_anchors":{"post":{"operationId":"createInterview_plan_draftsActionsUpdate_anchors","summary":"Upsert behavioral anchors verbatim","description":"Upsert behavioral anchors verbatim\n\n**Required scopes:** `interview_plans:write`\n\nUpserts behavioral anchors keyed by item id (competency, outcome, or skill). Each entry carries 1-4 levels; anchor levels are integers 1 through 4 and a level may appear once per item. An anchor keyed to an item id that does not exist in the draft returns 404 `draft_item_not_found`.\n\nAnchors use upsert + delete (not add/update pairs) because the store is keyed by item id — an upsert for an existing key replaces that key's levels wholesale.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/update_anchors \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.update_anchors\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"anchors\":{\"competency_1\":[{\"level\":1,\"description\":\"Repeats the customer's words back.\"},{\"level\":4,\"description\":\"Reframes the problem the customer missed.\"}]}}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/update_anchors\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.update_anchors\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"anchors\": {\n      \"competency_1\": [\n        {\n          \"level\": 1,\n          \"description\": \"Repeats the customer's words back.\"\n        },\n        {\n          \"level\": 4,\n          \"description\": \"Reframes the problem the customer missed.\"\n        }\n      ]\n    }\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.update_anchors"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"anchors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"level":{"type":"integer","minimum":1,"maximum":4},"description":{"type":"string","minLength":1,"maxLength":5000}},"required":["level","description"],"additionalProperties":false},"minItems":1,"maxItems":4}},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["anchors"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/interview_plan_drafts/actions/delete_anchors":{"post":{"operationId":"createInterview_plan_draftsActionsDelete_anchors","summary":"Delete behavioral-anchor entries by item id","description":"Delete behavioral-anchor entries by item id\n\n**Required scopes:** `interview_plans:write`\n\nRemoves the behavioral-anchor entries for the named item ids. Ids without an anchor entry return 404 `draft_item_not_found` naming the id.\n\n**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.\n\n**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`.\n\n**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.\n\n**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.\n\nWrites 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.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_anchors \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"action\":\"interview_plan.delete_anchors\",\"resource\":{\"type\":\"interview_plan_draft\",\"id\":\"ipd_…\"},\"input\":{\"item_ids\":[\"competency_2\"]}}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_plan_drafts/actions/delete_anchors\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({\n  \"action\": \"interview_plan.delete_anchors\",\n  \"resource\": {\n    \"type\": \"interview_plan_draft\",\n    \"id\": \"ipd_…\"\n  },\n  \"input\": {\n    \"item_ids\": [\n      \"competency_2\"\n    ]\n  }\n}),\n});\n```","tags":["Interview Plan Builder"],"deprecated":false,"security":[{"bearerAuth":["interview_plans:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StagedBuilderActionResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["interview_plan.delete_anchors"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string","pattern":"^ipd_[0-9A-Za-z]{16,64}$"}},"required":["type"],"additionalProperties":false},"input":{"type":"object","properties":{"item_ids":{"type":"array","items":{"type":"string","minLength":1,"maxLength":128},"minItems":1,"maxItems":100},"source_stage":{"type":"object","properties":{"stage":{"type":"string","enum":["questions_and_directions"]},"version":{"type":"integer","minimum":0}},"required":["stage"],"additionalProperties":false}},"required":["item_ids"],"additionalProperties":false}},"required":["action","input"],"additionalProperties":false}}}}}},"/v1/jobs":{"get":{"operationId":"listJobs","summary":"List jobs","description":"List jobs\n\n**Required scopes:** `jobs:read`\n\nRead-only. Returns internal hiring Job containers scoped to the token organization and live/test mode. Use Job Postings endpoints separately for candidate-facing publish/archive behavior.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/jobs?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Job"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"include_archived","in":"query","required":false,"description":"Set to true to include archived Jobs. Defaults to false.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createJobs","summary":"Create a job","description":"Create a job\n\n**Required scopes:** `jobs:write`\n\nDirect Job mutation. Use `Idempotency-Key` for create, update, close, and archive retries; replayed requests with the same key and body return the cached result instead of duplicating lifecycle writes. Jobs are organization and live/test partition scoped. Malformed, cross-org, wrong-mode, and inaccessible ids return `404 not_found` rather than leaking existence. Close and archive affect only the Job row in this slice; job postings, applications, and interview plans are not mutated. Live-mode Free organizations at the lifetime Job limit receive HTTP 409 `ats_job_limit_exceeded`; test-mode Job creation remains allowed at the live limit.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/jobs \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"title\":\"Account Executive\",\"status\":\"draft\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({ title: \"Account Executive\", status: \"draft\" }),\n});\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"department":{"type":"string","maxLength":200},"department_id":{"type":"string","pattern":"^dpt_[a-z0-9]+$","nullable":true},"location":{"type":"string","maxLength":200},"location_type":{"type":"string","enum":["remote","hybrid","onsite"]},"description":{"type":"string","maxLength":20000},"status":{"type":"string","enum":["draft","open","paused"]}},"required":["title"],"additionalProperties":false}}}}}},"/v1/jobs/{job_id}":{"get":{"operationId":"retrieveJobsJob_id","summary":"Retrieve a job","description":"Retrieve a job\n\n**Required scopes:** `jobs:read`\n\nRead-only. Returns bounded linked artifact summaries for existing `job_id` associations. Missing, malformed, cross-org, and wrong-mode ids return `404 not_found`.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/jobs/job_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs/job_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateJobsJob_id","summary":"Update a job","description":"Update a job\n\n**Required scopes:** `jobs:write`\n\nDirect Job mutation. Use `Idempotency-Key` for create, update, close, and archive retries; replayed requests with the same key and body return the cached result instead of duplicating lifecycle writes. Jobs are organization and live/test partition scoped. Malformed, cross-org, wrong-mode, and inaccessible ids return `404 not_found` rather than leaking existence. Close and archive affect only the Job row in this slice; job postings, applications, and interview plans are not mutated. Archived jobs reject updates with HTTP 409 `job_archived`; closed jobs reject further status changes with HTTP 409 `invalid_state_transition`.\n\n**Example (curl):**\n\n```bash\ncurl -X PATCH https://api.yardstick.team/v1/jobs/job_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"location\":\"Remote\",\"location_type\":\"remote\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs/job_abc123\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({ location: \"Remote\", location_type: \"remote\" }),\n});\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"department":{"type":"string","maxLength":200,"nullable":true},"department_id":{"type":"string","pattern":"^dpt_[a-z0-9]+$","nullable":true},"location":{"type":"string","maxLength":200,"nullable":true},"location_type":{"type":"string","enum":["remote","hybrid","onsite"],"nullable":true},"description":{"type":"string","maxLength":20000,"nullable":true},"status":{"type":"string","enum":["draft","open","paused"]}},"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/prospect_matches":{"get":{"operationId":"listJobsJob_idProspect_matches","summary":"GET /v1/jobs/{job_id}/prospect_matches","description":"GET /v1/jobs/{job_id}/prospect_matches\n\n**Required scopes:** `jobs:read`, `prospects:read`, `applications:read`","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:read","prospects:read","applications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/jobs/{job_id}/actions/close":{"post":{"operationId":"createJobsJob_idActionsClose","summary":"Close a job","description":"Close a job\n\n**Required scopes:** `jobs:write`\n\nDirect Job mutation. Use `Idempotency-Key` for create, update, close, and archive retries; replayed requests with the same key and body return the cached result instead of duplicating lifecycle writes. Jobs are organization and live/test partition scoped. Malformed, cross-org, wrong-mode, and inaccessible ids return `404 not_found` rather than leaking existence. Close and archive affect only the Job row in this slice; job postings, applications, and interview plans are not mutated.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/jobs/job_abc123/actions/close \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs/job_abc123/actions/close\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({}),\n}).then((r) => r.json());\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"200":{"description":"Job closed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/actions/archive":{"post":{"operationId":"createJobsJob_idActionsArchive","summary":"Archive a job","description":"Archive a job\n\n**Required scopes:** `jobs:write`\n\nDirect Job mutation. Use `Idempotency-Key` for create, update, close, and archive retries; replayed requests with the same key and body return the cached result instead of duplicating lifecycle writes. Jobs are organization and live/test partition scoped. Malformed, cross-org, wrong-mode, and inaccessible ids return `404 not_found` rather than leaking existence. Close and archive affect only the Job row in this slice; job postings, applications, and interview plans are not mutated.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/jobs/job_abc123/actions/archive \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/jobs/job_abc123/actions/archive\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({}),\n}).then((r) => r.json());\n```","tags":["Jobs"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"200":{"description":"Job archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/actions/attach_artifact":{"post":{"operationId":"createJobsJob_idActionsAttach_artifact","summary":"Attach an artifact to a job","description":"Attach an artifact to a job\n\n**Required scopes:** `jobs:write`\n\nRequired scopes: `jobs:write` plus the artifact's own write scope — `interview_plans:write` for artifact_type `interview_plan`, `job_postings:write` for `job_posting`, `applications:write` for `application`. The machine-readable `security` array lists only `jobs:write` because OpenAPI cannot express a scope that depends on the request body; the artifact write scope is enforced server-side and a caller missing it receives HTTP 403 `insufficient_scope`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/jobs/job_abc123/actions/attach_artifact \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"artifact_type\":\"job_posting\",\"artifact_id\":\"jp_xyz789\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/jobs/job_abc123/actions/attach_artifact\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      artifact_type: \"job_posting\",\n      artifact_id: \"jp_xyz789\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artifact_type":{"type":"string","enum":["interview_plan","job_posting","application"]},"artifact_id":{"type":"string","minLength":1}},"required":["artifact_type","artifact_id"],"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/actions/detach_artifact":{"post":{"operationId":"createJobsJob_idActionsDetach_artifact","summary":"Detach an artifact from a job","description":"Detach an artifact from a job\n\n**Required scopes:** `jobs:write`\n\nRequired scopes: `jobs:write` plus the artifact's own write scope — `interview_plans:write` for artifact_type `interview_plan`, `job_postings:write` for `job_posting`, `applications:write` for `application`. The machine-readable `security` array lists only `jobs:write` because OpenAPI cannot express a scope that depends on the request body; the artifact write scope is enforced server-side and a caller missing it receives HTTP 403 `insufficient_scope`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/jobs/job_abc123/actions/detach_artifact \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"artifact_type\":\"job_posting\",\"artifact_id\":\"jp_xyz789\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/jobs/job_abc123/actions/detach_artifact\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      artifact_type: \"job_posting\",\n      artifact_id: \"jp_xyz789\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["jobs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"artifact_type":{"type":"string","enum":["interview_plan","job_posting","application"]},"artifact_id":{"type":"string","minLength":1}},"required":["artifact_type","artifact_id"],"additionalProperties":false}}}}}},"/v1/departments":{"get":{"operationId":"listDepartments","summary":"GET /v1/departments","description":"GET /v1/departments\n\n**Required scopes:** `departments:read`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Department"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createDepartments","summary":"POST /v1/departments","description":"POST /v1/departments\n\n**Required scopes:** `departments:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:write"]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000,"nullable":true},"slug":{"type":"string","minLength":1,"maxLength":200}},"required":["name"],"additionalProperties":false}}}}}},"/v1/departments/{department_id}":{"get":{"operationId":"retrieveDepartmentsDepartment_id","summary":"GET /v1/departments/{department_id}","description":"GET /v1/departments/{department_id}\n\n**Required scopes:** `departments:read`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateDepartmentsDepartment_id","summary":"PATCH /v1/departments/{department_id}","description":"PATCH /v1/departments/{department_id}\n\n**Required scopes:** `departments:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Department"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000,"nullable":true},"slug":{"type":"string","minLength":1,"maxLength":200}},"additionalProperties":false}}}}}},"/v1/departments/{department_id}/members":{"get":{"operationId":"listDepartmentsDepartment_idMembers","summary":"GET /v1/departments/{department_id}/members","description":"GET /v1/departments/{department_id}/members\n\n**Required scopes:** `departments:read`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DepartmentMember"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createDepartmentsDepartment_idMembers","summary":"POST /v1/departments/{department_id}/members","description":"POST /v1/departments/{department_id}/members\n\n**Required scopes:** `departments:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentMember"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"person_id":{"type":"string","pattern":"^per_[a-z0-9]+$"}},"required":["person_id"],"additionalProperties":false}}}}}},"/v1/departments/{department_id}/invitations":{"get":{"operationId":"listDepartmentsDepartment_idInvitations","summary":"GET /v1/departments/{department_id}/invitations","description":"GET /v1/departments/{department_id}/invitations\n\n**Required scopes:** `invitations:read`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["invitations:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DepartmentInvitation"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createDepartmentsDepartment_idInvitations","summary":"POST /v1/departments/{department_id}/invitations","description":"POST /v1/departments/{department_id}/invitations\n\n**Required scopes:** `invitations:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["invitations:write"]}],"responses":{"201":{"description":"Invitation created and email queued.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentInvitationCreateResponse"}}}},"202":{"description":"Invitation created, but email delivery failed. The response contains no token or invitation URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentInvitationCreateResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","maxLength":320},"name":{"type":"string","maxLength":200},"full_name":{"type":"string","maxLength":200},"role":{"type":"string","enum":["department_lead","recruiter"]},"expires_in_hours":{"type":"integer","minimum":1,"maximum":720}},"required":["email","role"],"additionalProperties":false}}}}}},"/v1/departments/{department_id}/members/{person_id}":{"patch":{"operationId":"updateDepartmentsDepartment_idMembersPerson_id","summary":"PATCH /v1/departments/{department_id}/members/{person_id}","description":"PATCH /v1/departments/{department_id}/members/{person_id}\n\n**Required scopes:** `departments:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentMember"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string","enum":["lead"]}},"required":["role"],"additionalProperties":false}}}}},"delete":{"operationId":"deleteDepartmentsDepartment_idMembersPerson_id","summary":"DELETE /v1/departments/{department_id}/members/{person_id}","description":"DELETE /v1/departments/{department_id}/members/{person_id}\n\n**Required scopes:** `departments:write`","tags":["Departments"],"deprecated":false,"security":[{"bearerAuth":["departments:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DepartmentMember"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"department_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"person_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/access_grants":{"get":{"operationId":"listAccess_grants","summary":"GET /v1/access_grants","description":"GET /v1/access_grants\n\n**Required scopes:** `access_grants:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["access_grants:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createAccess_grants","summary":"POST /v1/access_grants","description":"POST /v1/access_grants\n\n**Required scopes:** `access_grants:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["access_grants:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"subject_person_id":{"type":"string","pattern":"^per_[a-z0-9]+$"},"scope":{"type":"string","enum":["job","department","application","report"]},"target_id":{"type":"string","pattern":"^(job|dpt|app|rpt)_[a-z0-9]+$"},"artifact_classes":{"type":"array","items":{"type":"string","enum":["scorecards","notes","decision_brief","calibration","reference_reports"]},"minItems":1},"reason":{"type":"string","minLength":20,"maxLength":2000},"effective_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time","nullable":true},"revocable":{"type":"boolean"}},"required":["subject_person_id","scope","target_id","artifact_classes","reason"],"additionalProperties":false}}}}}},"/v1/access_grants/{access_grant_id}":{"get":{"operationId":"retrieveAccess_grantsAccess_grant_id","summary":"GET /v1/access_grants/{access_grant_id}","description":"GET /v1/access_grants/{access_grant_id}\n\n**Required scopes:** `access_grants:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["access_grants:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/access_grants/{access_grant_id}/actions/revoke":{"post":{"operationId":"createAccess_grantsAccess_grant_idActionsRevoke","summary":"POST /v1/access_grants/{access_grant_id}/actions/revoke","description":"POST /v1/access_grants/{access_grant_id}/actions/revoke\n\n**Required scopes:** `access_grants:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["access_grants:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":10,"maxLength":2000}},"additionalProperties":false}}}}}},"/v1/job_postings":{"get":{"operationId":"listJob_postings","summary":"List job postings","description":"List job postings\n\n**Required scopes:** `job_postings:read`\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/job_postings?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/job_postings?limit=20\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/JobPosting"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createJob_postings","summary":"Create a draft job posting","description":"Create a draft job posting\n\n**Required scopes:** `job_postings:write`\n\nThe interview plan must already be attached to a Job. An unattached plan is rejected with HTTP 409 `interview_plan_not_linked_to_job`; attach it first via `POST /v1/jobs/{job_id}/actions/attach_artifact` with `artifact_type=interview_plan`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/job_postings \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"title\":\"Account Executive\",\"interview_plan_id\":\"ipd_…\",\"slug\":\"account-executive\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/job_postings\", {\n  method: \"POST\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n    \"Idempotency-Key\": crypto.randomUUID(),\n  },\n  body: JSON.stringify({\n    title: \"Account Executive\",\n    interview_plan_id: \"ipd_…\",\n    slug: \"account-executive\",\n  }),\n});\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:write"]}],"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPosting"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"interview_plan_id":{"type":"string","minLength":1},"slug":{"type":"string","minLength":1,"maxLength":200},"department":{"type":"string","maxLength":200},"group_id":{"type":"string","format":"uuid"},"location":{"type":"string","maxLength":200},"location_type":{"type":"string","enum":["remote","hybrid","onsite"]},"location_country":{"type":"string","description":"Assigned ISO 3166-1 alpha-2 country code. Lowercase input is accepted and normalized to uppercase."},"salary_min":{"type":"integer","minimum":0},"salary_max":{"type":"integer","minimum":0},"salary_currency":{"type":"string","minLength":3,"maxLength":8},"salary_display":{"type":"boolean"},"description":{"type":"string","maxLength":20000},"requirements":{"type":"string","maxLength":20000},"custom_questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"question":{"type":"string","minLength":1,"maxLength":2000},"type":{"type":"string","enum":["text","textarea","single-select","yes-no"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50}},"required":["id","question","type","required"],"additionalProperties":false},"maxItems":50}},"required":["title","interview_plan_id","slug"],"additionalProperties":false}}}}}},"/v1/job_postings/{job_posting_id}":{"get":{"operationId":"retrieveJob_postingsJob_posting_id","summary":"Retrieve a job posting","description":"Retrieve a job posting\n\n**Required scopes:** `job_postings:read`\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/job_postings/jp_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/job_postings/jp_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPosting"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_posting_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateJob_postingsJob_posting_id","summary":"Update a draft job posting","description":"Update a draft job posting\n\n**Required scopes:** `job_postings:write`\n\nArchived postings reject updates with HTTP 409 `posting_archived`.\n\n**Example (curl):**\n\n```bash\ncurl -X PATCH https://api.yardstick.team/v1/job_postings/jp_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"location\":\"Remote\",\"location_type\":\"remote\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/job_postings/jp_abc123\", {\n  method: \"PATCH\",\n  headers: {\n    Authorization: `Bearer ${process.env.YS_API_KEY}`,\n    \"Content-Type\": \"application/json\",\n  },\n  body: JSON.stringify({ location: \"Remote\", location_type: \"remote\" }),\n});\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPosting"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_posting_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","minLength":1,"maxLength":200},"department":{"type":"string","maxLength":200,"nullable":true},"group_id":{"type":"string","format":"uuid","nullable":true},"location":{"type":"string","maxLength":200,"nullable":true},"location_type":{"type":"string","enum":["remote","hybrid","onsite"]},"location_country":{"type":"string","description":"Assigned ISO 3166-1 alpha-2 country code. Lowercase input is accepted and normalized to uppercase.","nullable":true},"salary_min":{"type":"integer","minimum":0,"nullable":true},"salary_max":{"type":"integer","minimum":0,"nullable":true},"salary_currency":{"type":"string","minLength":3,"maxLength":8},"salary_display":{"type":"boolean"},"description":{"type":"string","maxLength":20000,"nullable":true},"requirements":{"type":"string","maxLength":20000,"nullable":true},"custom_questions":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":120},"question":{"type":"string","minLength":1,"maxLength":2000},"type":{"type":"string","enum":["text","textarea","single-select","yes-no"]},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"maxItems":50}},"required":["id","question","type","required"],"additionalProperties":false},"maxItems":50}},"additionalProperties":false}}}}}},"/v1/job_postings/{job_posting_id}/actions/validate_draft":{"post":{"operationId":"createJob_postingsJob_posting_idActionsValidate_draft","summary":"Validate a draft job posting for publish-readiness","description":"Validate a draft job posting for publish-readiness\n\n**Required scopes:** `job_postings:read`\n\nRead-only. Returns blockers describing the fields that would prevent publishing; does not mutate the posting.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/job_postings/jp_abc123/actions/validate_draft \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/job_postings/jp_abc123/actions/validate_draft\",\n  {\n    method: \"POST\",\n    headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n  },\n).then((r) => r.json());\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingValidationResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_posting_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/job_postings/{job_posting_id}/actions/publish":{"post":{"operationId":"createJob_postingsJob_posting_idActionsPublish","summary":"Publish a job posting (preview→bind)","description":"Publish a job posting (preview→bind)\n\n**Required scopes:** `job_postings:write`, `job_postings:publish`\n\nPreview→bind flow. Calling without a `binding` returns HTTP 202 with the approval-required envelope (no mutation). To execute, re-issue with `binding` echoing the preview's `preview_hash`, `approved_action_key`, `approved_input_hash`, `approved_idempotency_key`, and `resource_version_precondition`. The `Idempotency-Key` must match between calls. Preview responses are not cached; bind responses are cached so retrying the bind under the same Idempotency-Key replays the original result without re-executing the mutation.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/job_postings/jp_abc123/actions/publish \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/job_postings/jp_abc123/actions/publish\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({}),\n  },\n).then((r) => r.json());\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:write","job_postings:publish"]}],"responses":{"200":{"description":"Bind succeeded — job posting published.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPosting"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_posting_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"additionalProperties":false}}}}}},"/v1/job_postings/{job_posting_id}/actions/archive":{"post":{"operationId":"createJob_postingsJob_posting_idActionsArchive","summary":"Archive a job posting (preview→bind)","description":"Archive a job posting (preview→bind)\n\n**Required scopes:** `job_postings:write`, `job_postings:archive`\n\nPreview→bind flow. Calling without a `binding` returns HTTP 202 with the approval-required envelope (no mutation). To execute, re-issue with `binding` echoing the preview's `preview_hash`, `approved_action_key`, `approved_input_hash`, `approved_idempotency_key`, and `resource_version_precondition`. The `Idempotency-Key` must match between calls. Preview responses are not cached; bind responses are cached so retrying the bind under the same Idempotency-Key replays the original result without re-executing the mutation.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/job_postings/jp_abc123/actions/archive \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/job_postings/jp_abc123/actions/archive\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({}),\n  },\n).then((r) => r.json());\n```","tags":["Job Postings"],"deprecated":false,"security":[{"bearerAuth":["job_postings:write","job_postings:archive"]}],"responses":{"200":{"description":"Bind succeeded — job posting archived.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPosting"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_posting_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"additionalProperties":false}}}}}},"/v1/applications/{application_id}/interview_sessions/actions/ensure":{"post":{"operationId":"createApplicationsApplication_idInterview_sessionsActionsEnsure","summary":"Ensure an interview session for an application round","description":"Ensure an interview session for an application round\n\n**Required scopes:** `interview_sessions:write`\n\nCreates or reuses the interview session needed before scheduling readiness, link generation, interview start/complete, and scorecard flows. Requires a secret key with `interview_sessions:write`; publishable keys are denied. The server validates application org/mode, archive state, interview plan, and round membership, then returns a redacted `is_...` session envelope. Unavailable setup targets return the same safe not-found envelope and do not mutate. Integrations must use this public API setup path rather than directly inserting interview session rows.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/applications/app_def456/interview_sessions/actions/ensure \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"interview_plan_id\":\"ipd_…\",\"round_id\":\"round-technical\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/interview_sessions/actions/ensure\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      interview_plan_id: \"ipd_…\",\n      round_id: \"round-technical\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:write"]}],"responses":{"200":{"description":"Interview session created or reused. The response is redacted and carries the `is_...` id for downstream scheduling and interview-evaluation calls.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSessionEnsureResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"interview_plan_id":{"type":"string","description":"Optional `ipd_...` assertion. When present it must match the application plan."},"round_id":{"type":"string","minLength":1,"description":"Stable round id from the application's published interview plan."},"round_title":{"type":"string","description":"Optional caller hint. The server always uses the trusted stored round title."}},"required":["round_id"],"additionalProperties":false}}}}}},"/v1/interview_sessions/{interview_session_id}/actions/assign_interviewer":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsAssign_interviewer","summary":"Assign an interviewer to an interview session","description":"Assign an interviewer to an interview session\n\n**Required scopes:** `interview_sessions:write`\n\nAdds an organization member as an interviewer for an existing, caller-owned interview session. Requires a secret key with `interview_sessions:write`; publishable keys are denied. Re-assigning the same interviewer is an idempotent no-op and returns `reused: true`. Assigning a second interviewer is allowed, but scheduling readiness returns `INTERVIEWER_ASSIGNMENT_AMBIGUOUS` until the session has exactly one interviewer again. The response includes `user_tasks` booleans derived from the actual trigger-created rows: an `interview_session` task, plus an `application_interview` task when the application is `Scheduled` or `Interviewing`. Email notification is attempted by default; set `notify_interviewer: false` to opt out. `interviewer_email` reports a safe sent, already_sent, skipped, or email_not_sent outcome; email failure does not undo assignment. `suppressed` is non-null for sample data or unknown partition, including opt-out and self-assignment outcomes.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/assign_interviewer \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"interviewer_user_id\":\"00000000-0000-0000-0000-000000000000\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/assign_interviewer\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      interviewer_user_id: \"00000000-0000-0000-0000-000000000000\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:write"]}],"responses":{"200":{"description":"Interviewer assigned or reused. The response includes scheduling and user-task side-effect signals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSessionAssignInterviewerResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"notify_interviewer":{"type":"boolean","default":true,"description":"Email the assigned interviewer by default; set false to opt out."},"interviewer_user_id":{"type":"string","description":"The org-member interviewer to assign, as the `usr_<base32>` display id from the assignable-interviewer listing or as the raw UUID."}},"required":["interviewer_user_id"],"additionalProperties":false}}}}}},"/v1/interview_sessions/interviewers/available":{"get":{"operationId":"listInterview_sessionsInterviewersAvailable","summary":"List members who can be assigned as interviewers","description":"List members who can be assigned as interviewers\n\n**Required scopes:** `interview_sessions:read`\n\nRead-only. Returns the members of the token organization, newest membership first, so a caller holding only display ids can pick an interviewer without knowing a raw user UUID. Members whose profile record is missing are omitted. Paginate with `limit` and `starting_after`, passing the `usr_` id of the last entry of the previous page.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/interview_sessions/interviewers/available?limit=20' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/interviewers/available?limit=20\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AssignableInterviewer"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/interviewers":{"get":{"operationId":"listInterview_sessionsInterview_session_idInterviewers","summary":"List interviewers assigned to an interview session","description":"List interviewers assigned to an interview session\n\n**Required scopes:** `interview_sessions:read`\n\nRead-only. Returns an `object: \"list\"` envelope scoped by session org and live/test mode. Completed sessions remain inspectable. Rows are ordered primary first, then by `assigned_at` ascending, and expose only the raw interviewer UUID, primary flag, and assignment timestamp.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/interview_sessions/is_abc123/interviewers \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/interviewers\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSessionInterviewerListResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/unassign_interviewer":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsUnassign_interviewer","summary":"Unassign an interviewer from an interview session","description":"Unassign an interviewer from an interview session\n\n**Required scopes:** `interview_sessions:write`\n\nDeletes the scoped `(session, interviewer)` assignment row when present. Requires a secret key with `interview_sessions:write`; publishable keys are denied. Removing an interviewer that is not currently assigned is an idempotent no-op and returns `removed: 0`. The response recomputes `scheduling_ready` / `scheduling_blocker` from the remaining rows and includes `user_tasks` booleans derived from actual trigger side effects.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/unassign_interviewer \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"interviewer_user_id\":\"00000000-0000-0000-0000-000000000000\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/unassign_interviewer\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({\n      interviewer_user_id: \"00000000-0000-0000-0000-000000000000\",\n    }),\n  },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:write"]}],"responses":{"200":{"description":"Interviewer unassigned or confirmed absent. The response includes scheduling and user-task side-effect signals.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSessionUnassignInterviewerResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"interviewer_user_id":{"type":"string","description":"The interviewer to unassign, as the `usr_<base32>` display id or the raw UUID."}},"required":["interviewer_user_id"],"additionalProperties":false}}}}}},"/v1/interview_sessions/{interview_session_id}":{"get":{"operationId":"retrieveInterview_sessionsInterview_session_id","summary":"Retrieve an interview session","description":"Retrieve an interview session\n\n**Required scopes:** `interview_sessions:read`\n\nRead-only. Returns a redacted session envelope scoped by application org and mode. `interview_version_id` is a public `iv_...` display id when present, and scorecard criteria come from the session-bound version.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/interview_sessions/is_abc123 \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/interview_sessions/is_abc123\", {\n  headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` },\n}).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSession"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications/{application_id}/interview_sessions":{"get":{"operationId":"listApplicationsApplication_idInterview_sessions","summary":"List interview sessions for an application","description":"List interview sessions for an application\n\n**Required scopes:** `interview_sessions:read`\n\nRead-only. Lists application sessions in deterministic creation order. Each item uses the same redacted `interview_session` shape as retrieve.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/applications/app_def456/interview_sessions \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/applications/app_def456/interview_sessions\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterviewSessionList"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/readiness":{"get":{"operationId":"listInterview_sessionsInterview_session_idActionsReadiness","summary":"Check interview session scheduling readiness","description":"Check interview session scheduling readiness\n\n**Required scopes:** `scheduling:read`\n\nRead-only. Returns `{ ready: true }` when the session is schedulable, or a blocker envelope (`{ ready: false, blocker_code, blocker_message, blocker_metadata }`) identifying the recovery flow. Stable blocker codes cover interviewer assignment, provider setup, event-type mapping, and plan-lineage resolution: `INTERVIEWER_ASSIGNMENT_REQUIRED`, `INTERVIEWER_ASSIGNMENT_AMBIGUOUS`, `SCHEDULER_INTEGRATION_REQUIRED`, `SCHEDULER_WEBHOOK_SETUP_REQUIRED`, `SCHEDULER_EVENT_TYPE_MAPPING_MISSING`, `INTERVIEW_PLAN_NOT_FOUND`, `INTERVIEW_PLAN_AMBIGUOUS`, `INTERVIEW_PLAN_LINEAGE_MISMATCH`. When the mapping blocker fires, metadata may include the interview duration, mapping key, provider, integration id, assigned scheduler ids, and `settings_url` for `/admin/integrations/scheduling`; it does not include provider secrets. Plan-lineage blockers return safe application/job/session context, candidate plan counts, and plan source context without interview sequences or provider internals. Inherits the org-default rate limit applied by `withApi`; no `Idempotency-Key` semantics (idempotency keys are ignored on GET).\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/readiness \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/readiness\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["scheduling:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingReadinessResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/generate_link":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsGenerate_link","summary":"Generate a scheduling link for an interview session","description":"Generate a scheduling link for an interview session\n\n**Required scopes:** `scheduling:write`\n\nMints a fresh scheduling link bound to the session's assigned interviewer. Returns 200 with `{ scheduling_link, provider, expires_at, link_id }` on success, or 409 with `{ blocker_code, blocker_message, blocker_metadata }` when blocked. `provider` is `\"calcom\"` or `\"calendly\"`. **Regeneration:** each call generates a fresh scheduling link. Previous links remain valid until their TTL expires; use the returned `link_id` to revoke a prior link out-of-band if needed. **Idempotency:** supply `Idempotency-Key` to dedupe retries; replayed requests return the cached response without minting a second link. Inherits the default per-token rate limit applied by `withApi`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/generate_link \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/generate_link\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({}),\n  },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["scheduling:write"]}],"responses":{"200":{"description":"Link minted. Each call generates a fresh scheduling link; previous links remain valid until their TTL expires.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingGenerateLinkResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Blocked by a structured scheduling blocker. Body carries `blocker_code`, `blocker_message`, and `blocker_metadata`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingBlockerEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/cancel":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsCancel","summary":"Cancel a scheduled interview session","description":"Cancel a scheduled interview session\n\n**Required scopes:** `scheduling:write`\n\nCancels a scheduled interview round: releases the provider booking, invalidates every outstanding scheduling link for the round (an invalidated link is dead immediately, not at its TTL), cancels the synced calendar event, and — for manually scheduled rounds only — emails the candidate. Provider-booked rounds are not emailed, because the scheduler sends its own cancellation notice. **Body is optional.** `reason` (≤500 chars) is recorded on the `scheduling.session_cancelled` event and is the only place it is stored; `skip_provider: true` cancels in Yardstick without calling the scheduling provider — the retry path when the provider is failing. Unknown body fields are rejected with 400 rather than ignored. **Repeat cancels are safe:** `already_cancelled` means the round was already cancelled. The idempotent side effects (link invalidation, calendar cancel) are re-applied, but no provider call, candidate email, or `scheduling.session_cancelled` event is produced. A 409 refusal writes nothing, so it is equally safe to retry. **Check `candidate_email` on success:** `status: \"email_not_sent\"` means the cancel succeeded but the candidate was never told. **Idempotency:** supply `Idempotency-Key` to dedupe retries; replayed requests return the cached response. Inherits the default per-token rate limit applied by `withApi`.\n\n**Example (curl):**\n\n```bash\ncurl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/cancel \\\n  -H 'Authorization: Bearer ys_sk_live_…' \\\n  -H 'Content-Type: application/json' \\\n  -H 'Idempotency-Key: 7c3a…' \\\n  -d '{\"reason\":\"Hiring manager unavailable\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/cancel\",\n  {\n    method: \"POST\",\n    headers: {\n      Authorization: `Bearer ${process.env.YS_API_KEY}`,\n      \"Content-Type\": \"application/json\",\n      \"Idempotency-Key\": crypto.randomUUID(),\n    },\n    body: JSON.stringify({ reason: \"Hiring manager unavailable\" }),\n  },\n).then((r) => r.json());\n```","tags":["Scheduling"],"deprecated":false,"security":[{"bearerAuth":["scheduling:write"]}],"responses":{"200":{"description":"Round cancelled, or confirmed already cancelled. The provider booking is released, every outstanding scheduling link is invalidated, and the `candidate_email` / `suppressed` markers report the side effects.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCancelResponse"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"The round cannot be cancelled in its current state, or the provider rejected the cancellation. Nothing was written. Body carries `outcome`, `message`, `booking_status`, `session_status`, and `provider_failure_code`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SchedulingCancelRefusalEnvelope"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"reason":{"type":"string","minLength":1,"maxLength":500},"skip_provider":{"type":"boolean"}},"additionalProperties":false}}}}}},"/v1/interview_sessions/{interview_session_id}/actions/start":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsStart","summary":"POST /v1/interview_sessions/{interview_session_id}/actions/start","description":"POST /v1/interview_sessions/{interview_session_id}/actions/start\n\n**Required scopes:** `interview_sessions:write`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/complete":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsComplete","summary":"POST /v1/interview_sessions/{interview_session_id}/actions/complete","description":"POST /v1/interview_sessions/{interview_session_id}/actions/complete\n\n**Required scopes:** `interview_sessions:write`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["interview_sessions:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/interview_sessions/{interview_session_id}/actions/submit_scorecard":{"post":{"operationId":"createInterview_sessionsInterview_session_idActionsSubmit_scorecard","summary":"POST /v1/interview_sessions/{interview_session_id}/actions/submit_scorecard","description":"POST /v1/interview_sessions/{interview_session_id}/actions/submit_scorecard\n\n**Required scopes:** `scorecards:write`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["scorecards:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"interview_session_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications/{application_id}/actions/decision_brief":{"get":{"operationId":"listApplicationsApplication_idActionsDecision_brief","summary":"GET /v1/applications/{application_id}/actions/decision_brief","description":"GET /v1/applications/{application_id}/actions/decision_brief\n\n**Required scopes:** `decision_briefs:read`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["decision_briefs:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications/{application_id}/actions/decision_brief/regenerate":{"post":{"operationId":"createApplicationsApplication_idActionsDecision_briefRegenerate","summary":"POST /v1/applications/{application_id}/actions/decision_brief/regenerate","description":"POST /v1/applications/{application_id}/actions/decision_brief/regenerate\n\n**Required scopes:** `decision_briefs:write`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["decision_briefs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/applications/{application_id}/actions/record_final_recommendation":{"post":{"operationId":"createApplicationsApplication_idActionsRecord_final_recommendation","summary":"POST /v1/applications/{application_id}/actions/record_final_recommendation","description":"POST /v1/applications/{application_id}/actions/record_final_recommendation\n\n**Required scopes:** `decision_briefs:write`, `applications:read`","tags":["Interview Evaluation"],"deprecated":false,"security":[{"bearerAuth":["decision_briefs:write","applications:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/tasks":{"get":{"operationId":"listTasks","summary":"List the authenticated principal's tasks","description":"List the authenticated principal's tasks\n\n**Required scopes:** `tasks:read`\n\nReturns the open and recently-completed tasks assigned to the token principal's email, scoped to the token's organization and mode. The principal is resolved server-side from `api_tokens.created_by`; if the creator is no longer an org member, the request returns `422 token_principal_not_resolvable` and an admin must re-issue the token under a current member. See the Token principal lifecycle section in `docs/api/tasks-api.md`. Cursor-paginated via `starting_after=<tsk_…>` keyed on `(due_date, created_at, id)`. Review tasks include stack_key and job_id for grouping within the current organization and mode. Survey-token metadata is never returned; survey deep-links carry the `?token=auth` sentinel so the dashboard re-authenticates the viewer.\n\n**Example (curl):**\n\n```bash\ncurl 'https://api.yardstick.team/v1/tasks?limit=20&status=in_progress' \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/tasks?limit=20&status=in_progress\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Tasks"],"deprecated":false,"security":[{"bearerAuth":["tasks:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"limit","in":"query","required":false,"description":"Page size (1-100, default 20).","schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"starting_after","in":"query","required":false,"description":"Cursor: id of the last record from the previous page.","schema":{"type":"string"}},{"name":"task_type","in":"query","required":false,"description":"Filter by `user_tasks.task_type` (e.g. `application_interview`, `interview_session`, `survey_schedule`).","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Filter by task status (e.g. `pending`, `in_progress`, `completed`).","schema":{"type":"string"}},{"name":"due_before","in":"query","required":false,"description":"ISO-8601 UTC; only tasks due on or before this time.","schema":{"type":"string","format":"date-time"}},{"name":"due_after","in":"query","required":false,"description":"ISO-8601 UTC; only tasks due on or after this time.","schema":{"type":"string","format":"date-time"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/tasks/{task_id}/actions/respond":{"post":{"operationId":"createTasksTask_idActionsRespond","summary":"Answer an assigned review task","description":"Answer an assigned review task\n\n**Required scopes:** `tasks:write`\n\nUses the same response functions as the dashboard. Application reviews accept approve (moves to Candidates), reject, hold, or ask_recruiter. Scorecard reviews accept thumbs_up, thumbs_down, or note_to_recruiter. Recruiter-note responses require a nonempty note. Only the assigned reviewer with active organization membership may answer an open review. Closed reviews return 409; unsupported task kinds or answers return 400; an unassigned reviewer receives 403.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/tasks/tsk_abc123/actions/respond -X POST -H 'Authorization: Bearer ys_sk_live_…' -H 'Content-Type: application/json' -d '{\"decision\":\"approve\"}'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\"https://api.yardstick.team/v1/tasks/tsk_abc123/actions/respond\", { method: \"POST\", headers: { Authorization: \"Bearer YOUR_API_KEY\", \"Content-Type\": \"application/json\" }, body: JSON.stringify({ decision: \"approve\" }) });\n```","tags":["Tasks"],"deprecated":false,"security":[{"bearerAuth":["tasks:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"decision":{"type":"string","enum":["approve","reject","hold","ask_recruiter","thumbs_up","thumbs_down","note_to_recruiter"]},"note":{"type":"string","maxLength":10000}},"required":["decision"],"additionalProperties":false}}}}}},"/v1/tasks/{task_id}/actions/deep_link":{"get":{"operationId":"listTasksTask_idActionsDeep_link","summary":"Resolve a task to a dashboard deep link","description":"Resolve a task to a dashboard deep link\n\n**Required scopes:** `tasks:read`\n\nReturns `{ web_url, route, mode }` for the supplied `tsk_…` id. Mode-partitioned: a live token requesting a test-mode task receives `404 not_found` (never `403`) to avoid leaking cross-partition existence. If the underlying resource the task references has been deleted, the response is `410 resource_gone`. Survey and reviewer_evaluation tasks return URLs ending in `?token=auth`; the private survey-completion token is never included in the response.\n\n**Example (curl):**\n\n```bash\ncurl https://api.yardstick.team/v1/tasks/tsk_abc123/actions/deep_link \\\n  -H 'Authorization: Bearer ys_sk_live_…'\n```\n\n**Example (TypeScript):**\n\n```ts\nawait fetch(\n  \"https://api.yardstick.team/v1/tasks/tsk_abc123/actions/deep_link\",\n  { headers: { Authorization: `Bearer ${process.env.YS_API_KEY}` } },\n).then((r) => r.json());\n```","tags":["Tasks"],"deprecated":false,"security":[{"bearerAuth":["tasks:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"task_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/agency_collaboration/whoami":{"get":{"operationId":"listAgency_collaborationWhoami","summary":"GET /v1/agency_collaboration/whoami","description":"GET /v1/agency_collaboration/whoami\n\n**Required scopes:** `agency_collaboration:read`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/agency_collaboration/connections/request":{"post":{"operationId":"createAgency_collaborationConnectionsRequest","summary":"POST /v1/agency_collaboration/connections/request","description":"POST /v1/agency_collaboration/connections/request\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"customer_email":{"type":"string","format":"email","maxLength":320},"mode":{"type":"string","enum":["submission_vendor","trusted_recruiting_partner"],"default":"submission_vendor"}},"required":["customer_email"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/connections/accept":{"post":{"operationId":"createAgency_collaborationConnectionsAccept","summary":"POST /v1/agency_collaboration/connections/accept","description":"POST /v1/agency_collaboration/connections/accept\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_id":{"type":"string","minLength":1}},"required":["relationship_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/interview_plans/create":{"post":{"operationId":"createAgency_collaborationInterview_plansCreate","summary":"POST /v1/agency_collaboration/interview_plans/create","description":"POST /v1/agency_collaboration/interview_plans/create\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"title":{"type":"string","minLength":1,"maxLength":300},"role_name":{"type":"string","minLength":1,"maxLength":300},"additional_info":{"type":"string","maxLength":10000,"nullable":true}},"required":["title","role_name"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/interview_plans/copy":{"post":{"operationId":"createAgency_collaborationInterview_plansCopy","summary":"POST /v1/agency_collaboration/interview_plans/copy","description":"POST /v1/agency_collaboration/interview_plans/copy\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_plan_id":{"type":"string","minLength":1},"title":{"type":"string","minLength":1,"maxLength":300},"role_name":{"type":"string","minLength":1,"maxLength":300},"additional_info":{"type":"string","maxLength":10000,"nullable":true}},"required":["source_plan_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/interview_plans/share":{"post":{"operationId":"createAgency_collaborationInterview_plansShare","summary":"POST /v1/agency_collaboration/interview_plans/share","description":"POST /v1/agency_collaboration/interview_plans/share\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyCollaborationActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"source_plan_id":{"type":"string","minLength":1},"relationship_id":{"type":"string","minLength":1},"job_id":{"type":"string","minLength":1},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["source_plan_id","relationship_id","job_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/interview_plans/stop_share":{"post":{"operationId":"createAgency_collaborationInterview_plansStop_share","summary":"POST /v1/agency_collaboration/interview_plans/stop_share","description":"POST /v1/agency_collaboration/interview_plans/stop_share\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"share_id":{"type":"string","minLength":1}},"required":["share_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/submit":{"post":{"operationId":"createAgency_collaborationSubmissionsSubmit","summary":"POST /v1/agency_collaboration/submissions/submit","description":"POST /v1/agency_collaboration/submissions/submit\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyCollaborationActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/withdraw":{"post":{"operationId":"createAgency_collaborationSubmissionsWithdraw","summary":"POST /v1/agency_collaboration/submissions/withdraw","description":"POST /v1/agency_collaboration/submissions/withdraw\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/revise":{"post":{"operationId":"createAgency_collaborationSubmissionsRevise","summary":"POST /v1/agency_collaboration/submissions/revise","description":"POST /v1/agency_collaboration/submissions/revise\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/respond":{"post":{"operationId":"createAgency_collaborationSubmissionsRespond","summary":"POST /v1/agency_collaboration/submissions/respond","description":"POST /v1/agency_collaboration/submissions/respond\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"body":{"type":"string","minLength":1,"maxLength":2000},"attachments":{"type":"array","items":{"type":"string"},"maxItems":20}},"required":["submission_id","body"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/add_evidence":{"post":{"operationId":"createAgency_collaborationSubmissionsAdd_evidence","summary":"POST /v1/agency_collaboration/submissions/add_evidence","description":"POST /v1/agency_collaboration/submissions/add_evidence\n\n**Required scopes:** `agency_collaboration:write`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"body":{"type":"string","minLength":1,"maxLength":2000},"attachments":{"type":"array","items":{"type":"string"},"maxItems":20}},"required":["submission_id","body"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/submissions/dedup_preview":{"post":{"operationId":"createAgency_collaborationSubmissionsDedup_preview","summary":"POST /v1/agency_collaboration/submissions/dedup_preview","description":"POST /v1/agency_collaboration/submissions/dedup_preview\n\n**Required scopes:** `agency_collaboration:read`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"client_org_id":{"type":"string","minLength":1},"job_id":{"type":"string","minLength":1},"packet":{"type":"object","additionalProperties":{}}},"required":["client_org_id","job_id","packet"],"additionalProperties":false}}}}}},"/v1/agency_collaboration/feedback/candidates":{"post":{"operationId":"createAgency_collaborationFeedbackCandidates","summary":"POST /v1/agency_collaboration/feedback/candidates","description":"POST /v1/agency_collaboration/feedback/candidates\n\n**Required scopes:** `agency_collaboration:read`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false}}}}}},"/v1/agency_collaboration/feedback/detail":{"post":{"operationId":"createAgency_collaborationFeedbackDetail","summary":"POST /v1/agency_collaboration/feedback/detail","description":"POST /v1/agency_collaboration/feedback/detail\n\n**Required scopes:** `agency_collaboration:read`","tags":["Agency Collaboration"],"deprecated":false,"security":[{"bearerAuth":["agency_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/list":{"post":{"operationId":"createPartner_collaborationSubmissionsList","summary":"POST /v1/partner_collaboration/submissions/list","description":"POST /v1/partner_collaboration/submissions/list\n\n**Required scopes:** `partner_collaboration:read`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","format":"uuid"},"limit":{"type":"integer","minimum":1,"maximum":100}},"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/packet":{"post":{"operationId":"createPartner_collaborationSubmissionsPacket","summary":"POST /v1/partner_collaboration/submissions/packet","description":"POST /v1/partner_collaboration/submissions/packet\n\n**Required scopes:** `partner_collaboration:read`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/connections/mode":{"post":{"operationId":"createPartner_collaborationConnectionsMode","summary":"POST /v1/partner_collaboration/connections/mode","description":"POST /v1/partner_collaboration/connections/mode\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_id":{"type":"string","minLength":1},"mode":{"type":"string","enum":["submission_vendor","trusted_recruiting_partner"]}},"required":["relationship_id","mode"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/connections/assign":{"post":{"operationId":"createPartner_collaborationConnectionsAssign","summary":"POST /v1/partner_collaboration/connections/assign","description":"POST /v1/partner_collaboration/connections/assign\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_id":{"type":"string","minLength":1},"job_id":{"type":"string","format":"uuid"},"field_visibility":{"type":"object","additionalProperties":{}}},"required":["relationship_id","job_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/connections/visibility":{"post":{"operationId":"createPartner_collaborationConnectionsVisibility","summary":"POST /v1/partner_collaboration/connections/visibility","description":"POST /v1/partner_collaboration/connections/visibility\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_id":{"type":"string","minLength":1},"assigned_role_id":{"type":"string","minLength":1},"field_visibility":{"type":"object","additionalProperties":{}}},"required":["relationship_id","assigned_role_id","field_visibility"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/connections/revoke":{"post":{"operationId":"createPartner_collaborationConnectionsRevoke","summary":"POST /v1/partner_collaboration/connections/revoke","description":"POST /v1/partner_collaboration/connections/revoke\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyCollaborationActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"relationship_id":{"type":"string","minLength":1},"reason":{"type":"string","maxLength":500,"nullable":true},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["relationship_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/interview_plans/accept":{"post":{"operationId":"createPartner_collaborationInterview_plansAccept","summary":"POST /v1/partner_collaboration/interview_plans/accept","description":"POST /v1/partner_collaboration/interview_plans/accept\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"share_id":{"type":"string","minLength":1}},"required":["share_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/interview_plans/reject":{"post":{"operationId":"createPartner_collaborationInterview_plansReject","summary":"POST /v1/partner_collaboration/interview_plans/reject","description":"POST /v1/partner_collaboration/interview_plans/reject\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"share_id":{"type":"string","minLength":1}},"required":["share_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/accept":{"post":{"operationId":"createPartner_collaborationSubmissionsAccept","summary":"POST /v1/partner_collaboration/submissions/accept","description":"POST /v1/partner_collaboration/submissions/accept\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyCollaborationActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["submission_id"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/reject":{"post":{"operationId":"createPartner_collaborationSubmissionsReject","summary":"POST /v1/partner_collaboration/submissions/reject","description":"POST /v1/partner_collaboration/submissions/reject\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"reason_category":{"type":"string","enum":["need_provenance","possible_duplicate","availability","comp","other"]}},"required":["submission_id","reason_category"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/clarify":{"post":{"operationId":"createPartner_collaborationSubmissionsClarify","summary":"POST /v1/partner_collaboration/submissions/clarify","description":"POST /v1/partner_collaboration/submissions/clarify\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"reason_category":{"type":"string","enum":["need_provenance","possible_duplicate","availability","comp","other"]},"shared_note":{"type":"string","maxLength":2000,"nullable":true}},"required":["submission_id","reason_category"],"additionalProperties":false}}}}}},"/v1/partner_collaboration/submissions/resolve_ownership":{"post":{"operationId":"createPartner_collaborationSubmissionsResolve_ownership","summary":"POST /v1/partner_collaboration/submissions/resolve_ownership","description":"POST /v1/partner_collaboration/submissions/resolve_ownership\n\n**Required scopes:** `partner_collaboration:write`","tags":["Partner Collaboration"],"deprecated":false,"security":[{"bearerAuth":["partner_collaboration:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Approval-required preview. Re-issue with `binding` echoing the listed fields to execute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgencyCollaborationActionPreview"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","minLength":1},"resolution":{"type":"string","enum":["award","keep_separate"]},"awarded_submission_id":{"type":"string","minLength":1}},"required":["submission_id","resolution"],"additionalProperties":false}}}}}},"/v1/pipelines":{"get":{"operationId":"listPipelines","summary":"GET /v1/pipelines","description":"GET /v1/pipelines\n\n**Required scopes:** `pipelines:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createPipelines","summary":"POST /v1/pipelines","description":"POST /v1/pipelines\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,62}$"},"description":{"type":"string","maxLength":2000,"nullable":true},"stages":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,62}$"},"stage_kind":{"type":"string","enum":["normal","offer","hired","rejected","terminal"]},"approval_scope":{"type":"string","enum":["applications:offer","applications:hire","applications:reject","applications:withdraw"],"nullable":true},"is_terminal":{"type":"boolean"},"action_gates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["scorecard_submitted"]}},"required":["type"],"additionalProperties":false},"maxItems":20}},"required":["name","slug","stage_kind"],"additionalProperties":false},"maxItems":100}},"required":["name","slug"],"additionalProperties":false}}}}}},"/v1/pipelines/{pipeline_id}":{"get":{"operationId":"retrievePipelinesPipeline_id","summary":"GET /v1/pipelines/{pipeline_id}","description":"GET /v1/pipelines/{pipeline_id}\n\n**Required scopes:** `pipelines:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updatePipelinesPipeline_id","summary":"PATCH /v1/pipelines/{pipeline_id}","description":"PATCH /v1/pipelines/{pipeline_id}\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"description":{"type":"string","maxLength":2000,"nullable":true},"is_active":{"type":"boolean"}},"additionalProperties":false}}}}}},"/v1/pipelines/{pipeline_id}/actions/clone":{"post":{"operationId":"createPipelinesPipeline_idActionsClone","summary":"POST /v1/pipelines/{pipeline_id}/actions/clone","description":"POST /v1/pipelines/{pipeline_id}/actions/clone\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"copy_rules":{"type":"boolean"},"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9_-]{0,62}$"}},"required":["name","slug"],"additionalProperties":false}}}}}},"/v1/pipelines/{pipeline_id}/stages":{"post":{"operationId":"createPipelinesPipeline_idStages","summary":"POST /v1/pipelines/{pipeline_id}/stages","description":"POST /v1/pipelines/{pipeline_id}/stages\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,62}$"},"stage_kind":{"type":"string","enum":["normal","offer","hired","rejected","terminal"]},"approval_scope":{"type":"string","enum":["applications:offer","applications:hire","applications:reject","applications:withdraw"],"nullable":true},"is_terminal":{"type":"boolean"},"action_gates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["scorecard_submitted"]}},"required":["type"],"additionalProperties":false},"maxItems":20},"position":{"type":"integer","minimum":1}},"required":["name","slug","stage_kind"],"additionalProperties":false}}}}}},"/v1/pipelines/{pipeline_id}/stages/{stage_id}":{"patch":{"operationId":"updatePipelinesPipeline_idStagesStage_id","summary":"PATCH /v1/pipelines/{pipeline_id}/stages/{stage_id}","description":"PATCH /v1/pipelines/{pipeline_id}/stages/{stage_id}\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9_]{0,62}$"},"stage_kind":{"type":"string","enum":["normal","offer","hired","rejected","terminal"]},"approval_scope":{"type":"string","enum":["applications:offer","applications:hire","applications:reject","applications:withdraw"],"nullable":true},"is_terminal":{"type":"boolean"},"is_active":{"type":"boolean"},"action_gates":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["scorecard_submitted"]}},"required":["type"],"additionalProperties":false},"maxItems":20}},"additionalProperties":false}}}}},"delete":{"operationId":"deletePipelinesPipeline_idStagesStage_id","summary":"DELETE /v1/pipelines/{pipeline_id}/stages/{stage_id}","description":"DELETE /v1/pipelines/{pipeline_id}/stages/{stage_id}\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/pipelines/{pipeline_id}/actions/reorder_stages":{"post":{"operationId":"createPipelinesPipeline_idActionsReorder_stages","summary":"POST /v1/pipelines/{pipeline_id}/actions/reorder_stages","description":"POST /v1/pipelines/{pipeline_id}/actions/reorder_stages\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"stage_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":200}},"required":["stage_ids"],"additionalProperties":false}}}}}},"/v1/pipelines/{pipeline_id}/stages/{stage_id}/actions/bind_delete":{"post":{"operationId":"createPipelinesPipeline_idStagesStage_idActionsBind_delete","summary":"POST /v1/pipelines/{pipeline_id}/stages/{stage_id}/actions/bind_delete","description":"POST /v1/pipelines/{pipeline_id}/stages/{stage_id}/actions/bind_delete\n\n**Required scopes:** `pipelines:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"binding":{"type":"object","properties":{"preview_hash":{"type":"string","minLength":1},"approved_action_key":{"type":"string","minLength":1},"approved_input_hash":{"type":"string","minLength":1},"approved_idempotency_key":{"type":"string","minLength":1},"resource_version_precondition":{"type":"string","minLength":1}},"required":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/actions/assign_pipeline":{"post":{"operationId":"createJobsJob_idActionsAssign_pipeline","summary":"POST /v1/jobs/{job_id}/actions/assign_pipeline","description":"POST /v1/jobs/{job_id}/actions/assign_pipeline\n\n**Required scopes:** `pipelines:write`, `jobs:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write","jobs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_id":{"type":"string","minLength":1,"nullable":true},"stage_mapping":{"type":"object","additionalProperties":{"type":"string","minLength":1}},"preview":{"type":"boolean"}},"required":["pipeline_id"],"additionalProperties":false}}}}}},"/v1/jobs/{job_id}/actions/assign_pipeline/preview":{"post":{"operationId":"previewJobPipelineAssignment","summary":"POST /v1/jobs/{job_id}/actions/assign_pipeline/preview","description":"POST /v1/jobs/{job_id}/actions/assign_pipeline/preview\n\n**Required scopes:** `pipelines:write`, `jobs:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["pipelines:write","jobs:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_id":{"type":"string","minLength":1,"nullable":true},"stage_mapping":{"type":"object","additionalProperties":{"type":"string","minLength":1}},"preview":{"type":"boolean"}},"required":["pipeline_id"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/list":{"post":{"operationId":"listAutomationStarters","summary":"POST /v1/automation-rules/actions/starters/list","description":"POST /v1/automation-rules/actions/starters/list\n\n**Required scopes:** `automation_rules:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{},"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/create":{"post":{"operationId":"createAutomationStarter","summary":"POST /v1/automation-rules/actions/starters/create","description":"POST /v1/automation-rules/actions/starters/create\n\n**Required scopes:** `automation_rules:read`, `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200},"rules":{"type":"array","items":{"type":"object","additionalProperties":{}},"maxItems":200}},"required":["name","rules"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/rename":{"post":{"operationId":"renameAutomationStarter","summary":"POST /v1/automation-rules/actions/starters/rename","description":"POST /v1/automation-rules/actions/starters/rename\n\n**Required scopes:** `automation_rules:read`, `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starter_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["starter_id","name"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/delete":{"post":{"operationId":"deleteAutomationStarter","summary":"POST /v1/automation-rules/actions/starters/delete","description":"POST /v1/automation-rules/actions/starters/delete\n\n**Required scopes:** `automation_rules:read`, `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"starter_id":{"type":"string","minLength":1}},"required":["starter_id"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/save_job":{"post":{"operationId":"saveJobAutomationStarter","summary":"POST /v1/automation-rules/actions/starters/save_job","description":"POST /v1/automation-rules/actions/starters/save_job\n\n**Required scopes:** `automation_rules:read`, `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","minLength":1},"name":{"type":"string","minLength":1,"maxLength":200}},"required":["job_id","name"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/preview":{"post":{"operationId":"previewAutomationCopy","summary":"POST /v1/automation-rules/actions/starters/preview","description":"POST /v1/automation-rules/actions/starters/preview\n\n**Required scopes:** `automation_rules:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","minLength":1},"source":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["starter"]},"id":{"type":"string","minLength":1}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["job"]},"id":{"type":"string","minLength":1}},"required":["type","id"],"additionalProperties":false}]},"source_digest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"matches":{"type":"object","additionalProperties":{"type":"object","properties":{"steps":{"type":"object","additionalProperties":{"type":"string","minLength":1,"nullable":true}},"stage_id":{"type":"string","minLength":1,"nullable":true}},"additionalProperties":false}}},"required":["job_id","source"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/starters/apply":{"post":{"operationId":"applyAutomationCopy","summary":"POST /v1/automation-rules/actions/starters/apply","description":"POST /v1/automation-rules/actions/starters/apply\n\n**Required scopes:** `automation_rules:read`, `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: idempotency key reuse, or an enabled Update scheduling rule already covers these interview steps. An automation_rule_overlap error includes blocking_rule with its id, name and url.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AutomationRuleOverlap"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"job_id":{"type":"string","minLength":1},"source":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["starter"]},"id":{"type":"string","minLength":1}},"required":["type","id"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["job"]},"id":{"type":"string","minLength":1}},"required":["type","id"],"additionalProperties":false}]},"source_digest":{"type":"string","pattern":"^[a-f0-9]{64}$"},"matches":{"type":"object","additionalProperties":{"type":"object","properties":{"steps":{"type":"object","additionalProperties":{"type":"string","minLength":1,"nullable":true}},"stage_id":{"type":"string","minLength":1,"nullable":true}},"additionalProperties":false}}},"required":["job_id","source"],"additionalProperties":false}}}}}},"/v1/automation-rules/{rule_id}/preview":{"post":{"operationId":"previewAutomationRule","summary":"POST /v1/automation-rules/{rule_id}/preview","description":"POST /v1/automation-rules/{rule_id}/preview\n\n**Required scopes:** `automation_rules:read`, `applications:read`, `people:read` Assigned interviewer changes (assignment_changed) and Update scheduling (update_scheduling) belong to job rules targeting candidate interviews. The action accepts template_key (default updated_scheduling_invitation), delivery (auto_send or auto_draft_review, default review), and task: { assignee: recruiter or { user_id }, title, due_in?: { value, unit: days or hours } }. Timing is always immediate and delivery_mode mirrors action.delivery. Enabled Update scheduling rules cannot overlap steps on the same job. The recommended starter begins disabled. Saved-rule preview makes no changes and uses the current interview state; manually shared links without a recorded send cannot be detected.","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read","applications:read","people:read"]}],"responses":{"200":{"description":"Resolved recipients, sender, rendered email, links and missing prerequisites for this application. Executes no action.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"rule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"application_id":{"type":"string","minLength":1}},"required":["application_id"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/copy":{"post":{"operationId":"copyAutomationRule","summary":"POST /v1/automation-rules/actions/copy","description":"POST /v1/automation-rules/actions/copy\n\n**Required scopes:** `automation_rules:write`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"200":{"description":"Independent copies of one rule. Unmatched targets are copied off and flagged.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: idempotency key reuse, or an enabled Update scheduling rule already covers these interview steps. An automation_rule_overlap error includes blocking_rule with its id, name and url.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AutomationRuleOverlap"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rule_id":{"type":"string","minLength":1},"job_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50},"pipeline_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":50}},"required":["rule_id"],"additionalProperties":false}}}}}},"/v1/automation-rules/actions/bulk":{"post":{"operationId":"bulkAutomationRules","summary":"POST /v1/automation-rules/actions/bulk","description":"POST /v1/automation-rules/actions/bulk\n\n**Required scopes:** `automation_rules:write`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"200":{"description":"Affected rules and skipped rules. Show preview to the user and get confirmation before apply. Apply requires exact rule_ids returned by preview, never a filter. Pick a step rules cannot be switched on. Shared pipeline rules change for every job on that pipeline, including jobs outside the filter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationRuleBulkResult"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: idempotency key reuse, or an enabled Update scheduling rule already covers these interview steps. An automation_rule_overlap error includes blocking_rule with its id, name and url.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AutomationRuleOverlap"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"action":{"type":"string","enum":["on","off","delete"]},"mode":{"type":"string","enum":["preview","apply"]},"rule_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1,"maxItems":500},"filter":{"type":"object","properties":{"job_id":{"type":"string","minLength":1},"department_id":{"type":"string","minLength":1},"pipeline_id":{"type":"string","minLength":1},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","interview_time","assignment_changed"]},"email":{"type":"string","minLength":1,"maxLength":200},"is_active":{"type":"boolean"}},"additionalProperties":false}},"required":["action","mode"],"additionalProperties":false}}}}}},"/v1/automation-rules":{"get":{"operationId":"listAutomationRules","summary":"GET /v1/automation-rules","description":"GET /v1/automation-rules\n\n**Required scopes:** `automation_rules:read`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRule"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"job_id","in":"query","required":false,"description":"Job public id; includes inherited pipeline rules. null selects pipeline rules.","schema":{"type":"string"}},{"name":"department_id","in":"query","required":false,"description":"Department public id; includes inherited pipeline rules.","schema":{"type":"string"}},{"name":"pipeline_id","in":"query","required":false,"description":"Pipeline public id; includes shared rules and all job rules on that pipeline.","schema":{"type":"string"}},{"name":"trigger","in":"query","required":false,"description":"Rule trigger.","schema":{"type":"string"}},{"name":"email","in":"query","required":false,"description":"Email type or library template key.","schema":{"type":"string"}},{"name":"is_active","in":"query","required":false,"description":"Filter rules on or off.","schema":{"type":"boolean"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"post":{"operationId":"createAutomationRule","summary":"POST /v1/automation-rules","description":"POST /v1/automation-rules\n\n**Required scopes:** `automation_rules:write` Assigned interviewer changes (assignment_changed) and Update scheduling (update_scheduling) belong to job rules targeting candidate interviews. The action accepts template_key (default updated_scheduling_invitation), delivery (auto_send or auto_draft_review, default review), and task: { assignee: recruiter or { user_id }, title, due_in?: { value, unit: days or hours } }. Timing is always immediate and delivery_mode mirrors action.delivery. Enabled Update scheduling rules cannot overlap steps on the same job. The recommended starter begins disabled. Saved-rule preview makes no changes and uses the current interview state; manually shared links without a recorded send cannot be detected.","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"201":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationRule"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: idempotency key reuse, or an enabled Update scheduling rule already covers these interview steps. An automation_rule_overlap error includes blocking_rule with its id, name and url.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AutomationRuleOverlap"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_template_id":{"type":"string","minLength":1,"nullable":true},"job_id":{"type":"string","minLength":1,"nullable":true},"needs_step_pick":{"type":"boolean"},"name":{"type":"string","maxLength":200},"starter_key":{"type":"string","maxLength":100,"nullable":true},"job_scope":{"type":"string","enum":["all_compatible","selected"]},"job_posting_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"]},"timing":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["immediate"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["delay"]},"delayMinutes":{"type":"integer","minimum":0}},"required":["type","delayMinutes"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["interview_relative"]},"anchor":{"type":"string","enum":["start","end"]},"offsetMinutes":{"type":"integer"}},"required":["type","anchor","offsetMinutes"],"additionalProperties":false}]},"pipeline_stage_id":{"type":"string","minLength":1,"nullable":true,"default":null},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","assignment_changed","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["create_task"]},"task_type":{"type":"string","minLength":1,"maxLength":200,"description":"Add to My Tasks: scorecard_review on feedback_submitted, or coordination for a general follow-up. Same-kind tasks are stacked."},"task_title":{"type":"string","minLength":1,"maxLength":500,"description":"Task title; {candidate} resolves to the candidate name."},"assigned_user_email":{"type":"string","minLength":1,"maxLength":320},"assigned_role":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner"]},"due_date":{"type":"string","minLength":1,"maxLength":64,"description":"Existing fixed deadline; use due_in for recurring rules."},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false,"description":"Due this many days or hours after the rule fires; at most 365 days or 8760 hours. Cannot combine with due_date."},"context":{"type":"object","additionalProperties":{}}},"required":["type","task_type","task_title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["update_scheduling"]},"template_key":{"type":"string","minLength":1,"maxLength":200},"delivery":{"type":"string","enum":["auto_send","auto_draft_review"],"default":"auto_draft_review"},"task":{"type":"object","properties":{"assignee":{"anyOf":[{"type":"string","enum":["recruiter"]},{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"],"additionalProperties":false}]},"title":{"type":"string","minLength":1,"maxLength":500},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false}},"required":["assignee","title"],"additionalProperties":false}},"required":["type","task"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_email"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","interview_cancellation"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_scheduling_invitation"]},"interview_ids":{"type":"array","items":{"type":"string","minLength":1}},"format":{"type":"string","enum":["combined","separate"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type","interview_ids","format"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_preparation_email"]},"template_key":{"type":"string","enum":["candidate_preparation","onsite_logistics","technical_preparation"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_internal_email"]},"audience":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner","offer_approver","offer_requester"]},"template":{"type":"string","minLength":1,"maxLength":200}},"required":["type","audience","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["verify_calendar_event"]}},"required":["type"],"additionalProperties":false}]},"condition":{"type":"object","properties":{"step_position":{"anyOf":[{"type":"object","properties":{"which":{"type":"string","enum":["next"]}},"required":["which"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["first"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last_before"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"anchor_kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind","anchor_kind"],"additionalProperties":false}]},"public_application_only":{"type":"boolean"},"interview_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"step_kinds":{"type":"array","items":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"minItems":1}},"additionalProperties":true},"is_active":{"type":"boolean"},"position":{"type":"integer","minimum":0}},"required":["trigger","action"],"additionalProperties":false}}}}}},"/v1/automation-runs/{run_id}/retry":{"post":{"operationId":"retryAutomationRun","summary":"POST /v1/automation-runs/{run_id}/retry","description":"POST /v1/automation-runs/{run_id}/retry\n\n**Required scopes:** `automation_rules:write`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"200":{"description":"The original run is scheduled to try again. Only clean refusals are retryable; the rule must be active.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationRun"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"run_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/automation-runs":{"get":{"operationId":"listAutomationRuns","summary":"GET /v1/automation-runs","description":"GET /v1/automation-runs\n\n**Required scopes:** `automation_rules:read`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/ListEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AutomationRun"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"application_id","in":"query","required":false,"description":"Filter by application display id.","schema":{"type":"string"}},{"name":"rule_id","in":"query","required":false,"description":"Filter by workflow rule display id.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/automation-rules/{rule_id}":{"get":{"operationId":"getAutomationRule","summary":"GET /v1/automation-rules/{rule_id}","description":"GET /v1/automation-rules/{rule_id}\n\n**Required scopes:** `automation_rules:read`","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationRule"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"rule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]},"patch":{"operationId":"updateAutomationRule","summary":"PATCH /v1/automation-rules/{rule_id}","description":"PATCH /v1/automation-rules/{rule_id}\n\n**Required scopes:** `automation_rules:write` Assigned interviewer changes (assignment_changed) and Update scheduling (update_scheduling) belong to job rules targeting candidate interviews. The action accepts template_key (default updated_scheduling_invitation), delivery (auto_send or auto_draft_review, default review), and task: { assignee: recruiter or { user_id }, title, due_in?: { value, unit: days or hours } }. Timing is always immediate and delivery_mode mirrors action.delivery. Enabled Update scheduling rules cannot overlap steps on the same job. The recommended starter begins disabled. Saved-rule preview makes no changes and uses the current interview state; manually shared links without a recorded send cannot be detected.","tags":["Automation Rules"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AutomationRule"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict: idempotency key reuse, or an enabled Update scheduling rule already covers these interview steps. An automation_rule_overlap error includes blocking_rule with its id, name and url.","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/Error"},{"$ref":"#/components/schemas/AutomationRuleOverlap"}]}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"rule_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"pipeline_template_id":{"type":"string","minLength":1,"nullable":true},"job_id":{"type":"string","minLength":1,"nullable":true},"needs_step_pick":{"type":"boolean"},"name":{"type":"string","maxLength":200},"starter_key":{"type":"string","maxLength":100,"nullable":true},"job_scope":{"type":"string","enum":["all_compatible","selected"]},"job_posting_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"]},"timing":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["immediate"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["delay"]},"delayMinutes":{"type":"integer","minimum":0}},"required":["type","delayMinutes"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["interview_relative"]},"anchor":{"type":"string","enum":["start","end"]},"offsetMinutes":{"type":"integer"}},"required":["type","anchor","offsetMinutes"],"additionalProperties":false}]},"pipeline_stage_id":{"type":"string","minLength":1,"nullable":true},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","assignment_changed","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["create_task"]},"task_type":{"type":"string","minLength":1,"maxLength":200,"description":"Add to My Tasks: scorecard_review on feedback_submitted, or coordination for a general follow-up. Same-kind tasks are stacked."},"task_title":{"type":"string","minLength":1,"maxLength":500,"description":"Task title; {candidate} resolves to the candidate name."},"assigned_user_email":{"type":"string","minLength":1,"maxLength":320},"assigned_role":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner"]},"due_date":{"type":"string","minLength":1,"maxLength":64,"description":"Existing fixed deadline; use due_in for recurring rules."},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false,"description":"Due this many days or hours after the rule fires; at most 365 days or 8760 hours. Cannot combine with due_date."},"context":{"type":"object","additionalProperties":{}}},"required":["type","task_type","task_title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["update_scheduling"]},"template_key":{"type":"string","minLength":1,"maxLength":200},"delivery":{"type":"string","enum":["auto_send","auto_draft_review"],"default":"auto_draft_review"},"task":{"type":"object","properties":{"assignee":{"anyOf":[{"type":"string","enum":["recruiter"]},{"type":"object","properties":{"user_id":{"type":"string","format":"uuid"}},"required":["user_id"],"additionalProperties":false}]},"title":{"type":"string","minLength":1,"maxLength":500},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false}},"required":["assignee","title"],"additionalProperties":false}},"required":["type","task"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_email"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","interview_cancellation"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_scheduling_invitation"]},"interview_ids":{"type":"array","items":{"type":"string","minLength":1}},"format":{"type":"string","enum":["combined","separate"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type","interview_ids","format"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_preparation_email"]},"template_key":{"type":"string","enum":["candidate_preparation","onsite_logistics","technical_preparation"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_internal_email"]},"audience":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner","offer_approver","offer_requester"]},"template":{"type":"string","minLength":1,"maxLength":200}},"required":["type","audience","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["verify_calendar_event"]}},"required":["type"],"additionalProperties":false}]},"condition":{"type":"object","properties":{"step_position":{"anyOf":[{"type":"object","properties":{"which":{"type":"string","enum":["next"]}},"required":["which"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["first"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last_before"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"anchor_kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind","anchor_kind"],"additionalProperties":false}]},"public_application_only":{"type":"boolean"},"interview_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"step_kinds":{"type":"array","items":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"minItems":1}},"additionalProperties":true},"is_active":{"type":"boolean"},"position":{"type":"integer","minimum":0,"nullable":true}},"additionalProperties":false}}}}},"delete":{"operationId":"deleteAutomationRule","summary":"DELETE /v1/automation-rules/{rule_id}","description":"DELETE /v1/automation-rules/{rule_id}\n\n**Required scopes:** `automation_rules:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/automation-rules/actions/preview":{"post":{"operationId":"previewAutomationRuleActions","summary":"POST /v1/automation-rules/actions/preview","description":"POST /v1/automation-rules/actions/preview\n\n**Required scopes:** `automation_rules:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["automation_rules:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Supported for safe retry. Reuse the same key to receive the cached response without repeating the operation.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"application_id":{"type":"string","minLength":1},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","assignment_changed","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"pipeline_stage_id":{"type":"string","minLength":1}},"required":["application_id","trigger","pipeline_stage_id"],"additionalProperties":false}}}}}},"/v1/built-in-agents":{"get":{"operationId":"listBuiltInAgents","summary":"GET /v1/built-in-agents","description":"GET /v1/built-in-agents\n\n**Required scopes:** `built_in_agents:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["built_in_agents:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/built-in-agents/{built_in_agent_id}":{"get":{"operationId":"getBuiltInAgent","summary":"GET /v1/built-in-agents/{built_in_agent_id}","description":"GET /v1/built-in-agents/{built_in_agent_id}\n\n**Required scopes:** `built_in_agents:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["built_in_agents:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/built-in-agent-runs":{"get":{"operationId":"listBuiltInAgentRuns","summary":"GET /v1/built-in-agent-runs","description":"GET /v1/built-in-agent-runs\n\n**Required scopes:** `built_in_agents:read`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["built_in_agents:read"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/built-in-agents/{built_in_agent_id}/actions/enable":{"post":{"operationId":"enableBuiltInAgentPreview","summary":"POST /v1/built-in-agents/{built_in_agent_id}/actions/enable","description":"POST /v1/built-in-agents/{built_in_agent_id}/actions/enable\n\n**Required scopes:** `built_in_agents:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["built_in_agents:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}},"/v1/built-in-agents/{built_in_agent_id}/actions/configure":{"post":{"operationId":"configureBuiltInAgentPreview","summary":"POST /v1/built-in-agents/{built_in_agent_id}/actions/configure","description":"POST /v1/built-in-agents/{built_in_agent_id}/actions/configure\n\n**Required scopes:** `built_in_agents:write`","tags":["Other"],"deprecated":false,"security":[{"bearerAuth":["built_in_agents:write"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Authentication failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Permission denied (scope or feature flag)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Conflict (e.g. idempotency key reuse with different body)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Required for this operation. Reuse the same key to safely retry the same request.","schema":{"type":"string"}},{"name":"X-Request-Id","in":"header","required":false,"description":"Optional caller-supplied request identifier. Values must match `^[A-Za-z0-9_-]{1,128}$`; a valid value is echoed in the response `X-Request-Id` header, otherwise the API generates one.","schema":{"type":"string"}}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Yardstick API tokens. Format: `ys_(sk|pk)_(live|test)_<32+ chars>`. **Secret keys** (`ys_sk_…`) are server-only — using one from a browser origin returns `secret_key_browser_denied`. **Publishable keys** (`ys_pk_…`) are browser-safe and restricted to intake-only person creation."}},"schemas":{"Role":{"type":"object","required":["id","label","description","scopes","permissions"],"properties":{"id":{"type":"string","enum":["admin","recruiter","department_lead","hiring_manager","interviewer"]},"label":{"type":"string"},"description":{"type":"string"},"scopes":{"type":"array","items":{"type":"string","enum":["org","department","job"]}},"permissions":{"type":"object","additionalProperties":{"type":"string","enum":["read","write","manage"]},"description":"Map of resource → highest action the role holds. Resources are the locked v1 list documented in docs/product/roles-and-permissions/v1-decision-record.md Appendix A."}}},"RoleAssignmentScope":{"oneOf":[{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["org"]},"id":{"type":"string","pattern":"^org_[A-Z0-9]{26}$"}}},{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["department"]},"id":{"type":"string","pattern":"^dpt_[A-Z0-9]{26}$"}}},{"type":"object","required":["type","id"],"properties":{"type":{"type":"string","enum":["job"]},"id":{"type":"string","pattern":"^job_[A-Z0-9]{26}$"}}}],"discriminator":{"propertyName":"type"}},"RoleAssignment":{"type":"object","required":["id","user","role","scope","created_at"],"properties":{"id":{"type":"string","pattern":"^rola_[A-Z0-9]{26}$"},"user":{"type":"string","pattern":"^per_[A-Z0-9]{26}$"},"role":{"type":"string","enum":["admin","recruiter","department_lead","hiring_manager"]},"scope":{"$ref":"#/components/schemas/RoleAssignmentScope"},"created_at":{"type":"string","format":"date-time"},"created_by":{"type":["string","null"],"pattern":"^per_[A-Z0-9]{26}$"}}},"RoleAssignmentList":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RoleAssignment"}},"next_cursor":{"type":"string"}}},"Person":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `per_<base32>`"},"object":{"type":"string","enum":["person"]},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true},"phone":{"type":"string","nullable":true},"linkedin_url":{"type":"string","nullable":true},"resume_url":{"type":"string","nullable":true},"notes":{"type":"string","nullable":true},"livemode":{"type":"boolean"}},"required":["id","object","name","email","phone","linkedin_url","resume_url","notes","livemode"],"additionalProperties":false,"description":"Canonical person record for an applicant, lead, or contact."},"ResumeUploadSession":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `rus_<base32>`"},"object":{"type":"string","enum":["resume_upload_session"]},"person_id":{"type":"string","description":"Canonical `per_...` person id."},"upload_url":{"type":"string","description":"Single-path, short-lived (≤5 min), one-shot signed Storage URL. PUT the resume bytes here, then call finalize."},"object_path":{"type":"string","description":"Server-minted storage object key for the resume."},"expires_at":{"type":"string","description":"ISO-8601 UTC expiry of the signed upload URL."},"status":{"type":"string","enum":["pending"]}},"required":["id","object","person_id","upload_url","object_path","expires_at","status"],"additionalProperties":false,"description":"A pending resume upload session: hand the signed `upload_url` the bytes, then finalize."},"Application":{"type":"object","properties":{"is_candidate":{"type":"boolean","description":"Explicitly admitted to the interview process; Review Applications and Candidates are mutually exclusive per application."},"candidate_admission_id":{"type":"string","format":"uuid","nullable":true,"description":"Raw current admission UUID, required as expected_admission_id when undoing."},"candidate_admitted_at":{"type":"string","nullable":true},"candidate_admission_origin":{"type":"string","nullable":true},"candidate_activity_started_at":{"type":"string","nullable":true,"description":"Non-null after durable candidate activity; undo is then unavailable."},"id":{"type":"string","description":"Display id, e.g. `app_<base32>`"},"object":{"type":"string","enum":["application"]},"person_id":{"type":"string","description":"Canonical `per_...` person id."},"status":{"type":"string"},"stage":{"type":"string","description":"Deprecated free-form stage label. Status transitions never change it; read `pipeline_stage_id` for the pipeline position."},"pipeline_stage_id":{"type":"string","nullable":true,"description":"Display id (`pst_<base32>`) of the configured pipeline stage (board column) the application sits in; every status transition moves it to the stage mapped to the new status. Null when no configured stage is assigned."},"job_id":{"type":"string","nullable":true,"description":"Canonical `job_...` Job id when the application is linked to a Job; null for legacy or unlinked applications."},"job_posting_id":{"type":"string","nullable":true},"source":{"type":"object","properties":{"token_id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true}},"required":["token_id","label"],"additionalProperties":false},"livemode":{"type":"boolean"},"created":{"type":"string","nullable":true},"updated":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC; non-null when the application has been archived."},"archived_reason":{"type":"string","nullable":true,"description":"Free-text archive reason captured at archive time; nullable."}},"required":["is_candidate","candidate_admission_id","candidate_admitted_at","candidate_admission_origin","candidate_activity_started_at","id","object","person_id","status","stage","pipeline_stage_id","job_id","job_posting_id","source","livemode","created","updated","archived_at","archived_reason"],"additionalProperties":false,"description":"Canonical application tying a person to a job posting and hiring workflow. Use this resource when a user asks to create or add a candidate for a job."},"Opportunity":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `opp_<base32>`"},"object":{"type":"string","enum":["opportunity"]},"livemode":{"type":"boolean"},"dashboard_url":{"type":"string","nullable":true},"application":{"type":"object","properties":{"id":{"type":"string","description":"Canonical `app_...` application id."},"status":{"type":"string"},"stage":{"type":"string"},"created":{"type":"string","nullable":true},"updated":{"type":"string","nullable":true}},"required":["id","status","stage","created","updated"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string","description":"Canonical `per_...` person id."},"name":{"type":"string","nullable":true},"email":{"type":"string","nullable":true}},"required":["id","name","email"],"additionalProperties":false,"nullable":true},"interview_plan":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"role_name":{"type":"string","nullable":true}},"required":["id","title","role_name"],"additionalProperties":false,"nullable":true},"job_posting":{"type":"object","properties":{"id":{"type":"string"},"title":{"type":"string","nullable":true},"slug":{"type":"string","nullable":true}},"required":["id","title","slug"],"additionalProperties":false,"nullable":true}},"required":["id","object","livemode","dashboard_url","application","person","interview_plan","job_posting"],"additionalProperties":false,"description":"Read-only opportunity view over an application and its related person, plan, and posting metadata. These views appear in the Yardstick app as Candidates."},"ReportingSearchResult":{"type":"object","properties":{"object":{"type":"string","enum":["reporting_search_result"]},"query_family":{"type":"string","enum":["role_health_attention","funnel_snapshot_by_role","stale_opportunity_queue","missing_feedback_queue","candidate_pool_strength","source_signals","prospect_ops_summary"]},"filters":{"type":"object","additionalProperties":{},"description":"Normalized filters. Role scope is exact and uses job_id, job_posting_id, or role_label."},"data_gaps":{"type":"array","items":{"type":"string"},"description":"V1 reporting data-gap labels such as zero, unknown, not_tracked_yet, sample_size_warning, no_selected_role, no_data_in_date_window, or pre_instrumentation_history."},"results":{"type":"array","items":{}},"links":{"type":"object","properties":{"reporting_url":{"type":"string"}},"required":["reporting_url"],"additionalProperties":false},"metadata":{"type":"object","properties":{"livemode":{"type":"boolean"},"aggregation_status":{"type":"string"},"result_count":{"type":"integer","minimum":0},"truncated":{"type":"boolean"},"limit":{"type":"integer","minimum":1},"next_cursor":{"type":"string","nullable":true},"query_time_ms":{"type":"integer","minimum":0},"source":{"type":"string","enum":["v1_reporting_rpc"]},"truncation_reason":{"type":"string","enum":["limit","v1_row_cap"]}},"required":["livemode","aggregation_status","result_count","truncated","limit","next_cursor","query_time_ms","source"],"additionalProperties":false},"warnings":{"type":"array","items":{"type":"string"}}},"required":["object","query_family","filters","data_gaps","results","links","metadata","warnings"],"additionalProperties":false,"description":"Public reporting search response envelope for canonical V1 recruiting reporting families. Results are redacted summaries and counts, not raw notes or private scorecard text."},"Job":{"type":"object","properties":{"hiring_manager":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string","nullable":true}},"required":["id","name"],"additionalProperties":false,"nullable":true,"description":"Hiring manager user display id and name on job detail reads."},"id":{"type":"string","description":"Display id, e.g. `job_<base32>`"},"object":{"type":"string","enum":["job"]},"status":{"type":"string","enum":["draft","open","paused","closed","archived"]},"title":{"type":"string"},"department":{"type":"string","nullable":true,"description":"Legacy free-text department metadata. Preserved for backward compatibility. New integrations should use department_id for authoritative ownership; this field is advisory display text only.","deprecated":true},"department_id":{"type":"string","pattern":"^dpt_[A-Za-z0-9]+$","nullable":true,"description":"Display ID of the linked Department (internal Group). Use this for authoritative ownership. Null when the Job has no linked Department."},"department_name":{"type":"string","nullable":true,"description":"Live name of the linked Department (Group). Null when the Job has no linked Department."},"location":{"type":"string","nullable":true},"location_type":{"type":"string","enum":["remote","hybrid","onsite"],"nullable":true},"description":{"type":"string","nullable":true},"linked_artifacts":{"type":"object","properties":{"interview_plans":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"nullable":true},"count":{"type":"integer","nullable":true},"has_more":{"type":"boolean","nullable":true}},"required":["ids","count","has_more"],"additionalProperties":false},"job_postings":{"type":"object","properties":{"ids":{"type":"array","items":{"type":"string"},"nullable":true},"count":{"type":"integer","nullable":true},"has_more":{"type":"boolean","nullable":true}},"required":["ids","count","has_more"],"additionalProperties":false},"applications":{"type":"object","properties":{"count":{"type":"integer","nullable":true}},"required":["count"],"additionalProperties":false}},"required":["interview_plans","job_postings","applications"],"additionalProperties":false,"description":"Retrieve-by-id may include bounded linked artifact summaries; list responses return null summary fields to avoid per-row query cost."},"livemode":{"type":"boolean"},"created_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"updated_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"closed_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"archived_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"}},"required":["id","object","status","title","department","department_id","department_name","location","location_type","description","linked_artifacts","livemode","created_at","updated_at","closed_at","archived_at"],"additionalProperties":false,"description":"Internal hiring Job container. Jobs are separate from candidate-facing Job Postings; jobs:write does not publish or archive postings, mutate applications, or mutate interview plans."},"Department":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `dpt_<base32>`"},"object":{"type":"string","enum":["department"]},"organization_id":{"type":"string","description":"Display id, e.g. `org_<base32>`"},"name":{"type":"string"},"slug":{"type":"string"},"description":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"updated_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"}},"required":["id","object","organization_id","name","slug","description","created_at","updated_at"],"additionalProperties":false,"description":"Canonical Department resource backed by an internal Group."},"DepartmentMember":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `dpm_<base32>`"},"object":{"type":"string","enum":["department_member"]},"department_id":{"type":"string","description":"Display id, e.g. `dpt_<base32>`"},"person_id":{"type":"string","nullable":true,"description":"Display id, e.g. `per_<base32>`"},"role":{"type":"string"},"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"avatar_url":{"type":"string","nullable":true},"joined_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"}},"required":["id","object","department_id","person_id","role","email","name","avatar_url","joined_at"],"additionalProperties":false,"description":"Canonical Department member view."},"DepartmentInvitation":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `inv_<base32>`"},"object":{"type":"string","enum":["department_invitation"]},"department_id":{"type":"string","description":"Display id, e.g. `dpt_<base32>`"},"organization_id":{"type":"string","description":"Display id, e.g. `org_<base32>`"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"expires_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"created_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"updated_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"}},"required":["id","object","department_id","organization_id","email","name","role","status","accepted_at","expires_at","created_at","updated_at"],"additionalProperties":false,"description":"Canonical Department invitation view. Invitation secrets/tokens are never returned."},"DepartmentInvitationCreateResponse":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `inv_<base32>`"},"object":{"type":"string","enum":["department_invitation"]},"department_id":{"type":"string","description":"Display id, e.g. `dpt_<base32>`"},"organization_id":{"type":"string","description":"Display id, e.g. `org_<base32>`"},"email":{"type":"string"},"name":{"type":"string","nullable":true},"role":{"type":"string"},"status":{"type":"string"},"accepted_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"expires_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"created_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"updated_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"membership_created":{"type":"boolean","enum":[false],"description":"Invitation creation never creates membership; acceptance does."},"pending_membership_role":{"type":"string","enum":["lead","member"]},"email_delivery":{"type":"object","properties":{"status":{"type":"string","enum":["sent","failed"]}},"required":["status"],"additionalProperties":false}},"required":["id","object","department_id","organization_id","email","name","role","status","accepted_at","expires_at","created_at","updated_at","membership_created","pending_membership_role","email_delivery"],"additionalProperties":false,"description":"Department invitation create response. Invitation secrets/tokens are never returned."},"JobPosting":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `jp_<base32>`"},"object":{"type":"string","enum":["job_posting"]},"status":{"type":"string","enum":["draft","unpublished","published","archived"],"description":"Derived from is_published / published_at / archived_at."},"title":{"type":"string","nullable":true},"slug":{"type":"string"},"department":{"type":"string","nullable":true},"location":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"location_country":{"type":"string","nullable":true,"description":"Assigned ISO 3166-1 alpha-2 country code for the posting location. Drafts may be null; every new publish or republish requires a country, including remote roles."},"salary_min":{"type":"number","nullable":true},"salary_max":{"type":"number","nullable":true},"salary_currency":{"type":"string","nullable":true},"salary_display":{"type":"boolean","nullable":true},"description":{"type":"string","nullable":true},"requirements":{"type":"string","nullable":true},"custom_questions":{},"interview_plan_id":{"type":"string","description":"Display id of the bound interview plan (`ipd_<base32>`)."},"is_published":{"type":"boolean"},"published_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"archived_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"public_url":{"type":"string","nullable":true,"description":"Canonical public job board URL when published in live mode; uses PUBLIC_JOB_BOARD_BASE_URL with root jobs-board paths, falls back to PUBLIC_APP_BASE_URL with /careers paths, then defaults to https://jobs.yardstick.team. Null for drafts, archived postings, and test-mode postings."},"applications_count":{"type":"integer","nullable":true,"description":"Application count populated on retrieve-by-id; null on list responses to bound query cost."},"livemode":{"type":"boolean"},"created_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"updated_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"}},"required":["id","object","status","title","slug","department","location","location_type","location_country","salary_min","salary_max","salary_currency","salary_display","description","requirements","interview_plan_id","is_published","published_at","archived_at","public_url","applications_count","livemode","created_at","updated_at"],"additionalProperties":false,"description":"Canonical job posting record. Status is derived from is_published / published_at / archived_at."},"JobPostingValidationResult":{"type":"object","properties":{"object":{"type":"string","enum":["validation_result"]},"validation_passed":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"field":{"type":"string"},"reason":{"type":"string"}},"required":["field","reason"],"additionalProperties":false}},"posting_id":{"type":"string","description":"Display id, e.g. `jp_<base32>`"}},"required":["object","validation_passed","blockers","posting_id"],"additionalProperties":false,"description":"Read-only validate-draft response. blockers is empty iff validation_passed is true."},"JobPostingActionPreview":{"type":"object","properties":{"object":{"type":"string","description":"`<resource>_action_request`, e.g. `job_posting_action_request`."},"action":{"type":"string","description":"Canonical action key, e.g. `job_posting.publish`."},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["job_posting"]},"id":{"type":"string","description":"Display id, e.g. `jp_<base32>`"}},"required":["type","id"],"additionalProperties":false},"execution_mode":{"type":"string","enum":["approval_required"]},"approval_required":{"type":"boolean","enum":[true]},"mutated":{"type":"boolean","enum":[false]},"current_state":{},"proposed_state":{},"side_effects":{"type":"array","items":{"type":"string"}},"reason":{"type":"string","nullable":true},"approval":{"type":"object","properties":{"gate":{"type":"string","description":"Approval gate, e.g. `agent_confirmable`."},"reason":{"type":"string","nullable":true},"recovery":{"type":"string","description":"Recovery hint per the action registry, e.g. `approval_replay_required`, `compensating_action`."},"preview_required":{"type":"array","items":{"type":"string","enum":["action_key","resource_type","resource_id","resource_label","current_state","proposed_state","diff","affected_person","affected_application","side_effects","audit_event_type","api_event_type","idempotency_key","rollback_or_recovery","approval_actor","approval_timestamp"]}},"binding":{"type":"object","properties":{"required_fields":{"type":"array","items":{"type":"string","enum":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"]}},"approved_action_key":{"type":"string"},"approved_idempotency_key":{"type":"string","nullable":true},"preview_hash":{"type":"string","nullable":true},"input_hash":{"type":"string","nullable":true},"resource_version_precondition":{"type":"string","nullable":true}},"required":["required_fields","approved_action_key","approved_idempotency_key","preview_hash","input_hash","resource_version_precondition"],"additionalProperties":false}},"required":["gate","reason","recovery","preview_required","binding"],"additionalProperties":false}},"required":["object","action","resource","execution_mode","approval_required","mutated","side_effects","reason","approval"],"additionalProperties":false,"description":"HTTP 202 approval-preview envelope returned by sensitive job-posting actions when called without a `binding`. Echo the listed fields back in `binding` to execute the action."},"AgencyCollaborationActionPreview":{"type":"object","properties":{"object":{"type":"string","description":"`<resource>_action_request`, e.g. `agency_collaboration_action_request`."},"action":{"type":"string","description":"Canonical action key, e.g. `agency_collaboration.submission_submit` or `partner_collaboration.submission_accept`."},"resource":{"type":"object","properties":{"type":{"type":"string","description":"Resource family from the action-key prefix, e.g. `agency_collaboration` or `partner_collaboration`."},"id":{"type":"string","description":"Display id of the acted-on resource."}},"required":["type","id"],"additionalProperties":false},"execution_mode":{"type":"string","enum":["approval_required"]},"approval_required":{"type":"boolean","enum":[true]},"mutated":{"type":"boolean","enum":[false]},"current_state":{},"proposed_state":{},"side_effects":{"type":"array","items":{"type":"string"}},"reason":{"type":"string","nullable":true},"approval":{"type":"object","properties":{"gate":{"type":"string","description":"Approval gate, e.g. `agent_confirmable`."},"reason":{"type":"string","nullable":true},"recovery":{"type":"string","description":"Recovery hint per the action registry, e.g. `approval_replay_required`, `compensating_action`."},"preview_required":{"type":"array","items":{"type":"string","enum":["action_key","resource_type","resource_id","resource_label","current_state","proposed_state","diff","affected_person","affected_application","side_effects","audit_event_type","api_event_type","idempotency_key","rollback_or_recovery","approval_actor","approval_timestamp"]}},"binding":{"type":"object","properties":{"required_fields":{"type":"array","items":{"type":"string","enum":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"]}},"approved_action_key":{"type":"string"},"approved_idempotency_key":{"type":"string","nullable":true},"preview_hash":{"type":"string","nullable":true},"input_hash":{"type":"string","nullable":true},"resource_version_precondition":{"type":"string","nullable":true}},"required":["required_fields","approved_action_key","approved_idempotency_key","preview_hash","input_hash","resource_version_precondition"],"additionalProperties":false}},"required":["gate","reason","recovery","preview_required","binding"],"additionalProperties":false}},"required":["object","action","resource","execution_mode","approval_required","mutated","side_effects","reason","approval"],"additionalProperties":false,"description":"HTTP 202 approval-preview envelope returned by sensitive agency-collaboration actions (agency share/submit; customer revoke/accept/resolve-ownership) when called without a `binding`. Echo the listed fields back in `binding` to execute the action."},"EmailTemplatePolicy":{"type":"object","properties":{"object":{"type":"string","enum":["email_template"]},"template_key":{"type":"string"},"email_type":{"type":"string","nullable":true},"name":{"type":"string"},"audience":{"type":"string","enum":["candidate","internal"]},"is_default":{"type":"boolean"},"is_org_override":{"type":"boolean"},"used_by_count":{"type":"integer"},"used_by_active_count":{"type":"integer"},"used_by_inactive_count":{"type":"integer"},"template_id":{"type":"string","nullable":true},"version_id":{"type":"string","nullable":true},"version_number":{"type":"integer","nullable":true},"version_label":{"type":"string","nullable":true},"subject_template":{"type":"string","nullable":true},"html_body_template":{"type":"string","nullable":true},"text_body_template":{"type":"string","nullable":true},"allowed_variables":{"type":"array","items":{"type":"string"}}},"required":["object","template_key","email_type","name","audience","is_default","is_org_override","used_by_count","used_by_active_count","used_by_inactive_count","template_id","version_id","version_number","version_label","subject_template","html_body_template","text_body_template","allowed_variables"],"additionalProperties":false,"description":"Content-only email library entry. Built-in email_type or custom template_key identifies the email. Counts include active and inactive rules. No sending policy; absent content/version fields are null. Only owners and admins can manage the library."},"EmailTemplateDetail":{"type":"object","properties":{"object":{"type":"string","enum":["email_template"]},"template_key":{"type":"string"},"email_type":{"type":"string","nullable":true},"name":{"type":"string"},"audience":{"type":"string","enum":["candidate","internal"]},"is_default":{"type":"boolean"},"is_org_override":{"type":"boolean"},"used_by_count":{"type":"integer"},"used_by_active_count":{"type":"integer"},"used_by_inactive_count":{"type":"integer"},"template_id":{"type":"string","nullable":true},"version_id":{"type":"string","nullable":true},"version_number":{"type":"integer","nullable":true},"version_label":{"type":"string","nullable":true},"subject_template":{"type":"string","nullable":true},"html_body_template":{"type":"string","nullable":true},"text_body_template":{"type":"string","nullable":true},"allowed_variables":{"type":"array","items":{"type":"string"}}},"required":["object","template_key","email_type","name","audience","is_default","is_org_override","used_by_count","used_by_active_count","used_by_inactive_count","template_id","version_id","version_number","version_label","subject_template","html_body_template","text_body_template","allowed_variables"],"additionalProperties":false,"description":"Content-only email library entry. Built-in email_type or custom template_key identifies the email. Counts include active and inactive rules. No sending policy; absent content/version fields are null. Only owners and admins can manage the library."},"EmailTemplatePreview":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_preview"]},"subject":{"type":"string"},"html_body":{"type":"string"},"text_body":{"type":"string"},"variables":{"type":"object","additionalProperties":{"type":"string"}},"is_sample":{"type":"boolean","enum":[true]}},"required":["object","subject","html_body","text_body","variables","is_sample"],"additionalProperties":false},"EmailTemplateValidation":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_validation"]},"validation_passed":{"type":"boolean"},"blockers":{"type":"array","items":{}},"preview":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_preview"]},"subject":{"type":"string"},"html_body":{"type":"string"},"text_body":{"type":"string"},"variables":{"type":"object","additionalProperties":{"type":"string"}},"is_sample":{"type":"boolean","enum":[true]}},"required":["object","subject","html_body","text_body","variables","is_sample"],"additionalProperties":false}},"required":["object","validation_passed","blockers","preview"],"additionalProperties":false},"EmailTemplateVersion":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_version"]},"id":{"type":"string"},"number":{"type":"integer"},"label":{"type":"string"},"is_active":{"type":"boolean"},"is_default":{"type":"boolean"},"created":{"type":"string","nullable":true},"activated_at":{"type":"string","nullable":true},"subject_template":{"type":"string"},"html_body_template":{"type":"string"},"text_body_template":{"type":"string"}},"required":["object","id","number","label","is_active","is_default","created","activated_at","subject_template","html_body_template","text_body_template"],"additionalProperties":false},"EmailTemplatePublishResult":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_change"]},"operation":{"type":"string","enum":["create","update","duplicate","reset","delete","rollback"]},"template_key":{"type":"string"},"template_id":{"type":"string","nullable":true},"version_id":{"type":"string","nullable":true},"version_number":{"type":"integer","nullable":true},"deleted":{"type":"boolean"}},"required":["object","operation","template_key","template_id","version_id","version_number","deleted"],"additionalProperties":false},"EmailTemplateRollbackResult":{"type":"object","properties":{"object":{"type":"string","enum":["email_template_change"]},"operation":{"type":"string","enum":["create","update","duplicate","reset","delete","rollback"]},"template_key":{"type":"string"},"template_id":{"type":"string","nullable":true},"version_id":{"type":"string","nullable":true},"version_number":{"type":"integer","nullable":true},"deleted":{"type":"boolean"}},"required":["object","operation","template_key","template_id","version_id","version_number","deleted"],"additionalProperties":false},"EmailTemplateCustomizationPreview":{"type":"object","properties":{"object":{"type":"string","enum":["candidate_email_template_customization_preview"]},"email_type":{"type":"string"},"subject":{"type":"string"},"html_body":{"type":"string"},"text_body":{"type":"string"},"is_sample":{"type":"boolean","enum":[true]},"provenance":{"type":"object","properties":{"template_id":{"type":"string","nullable":true},"version_id":{"type":"string","nullable":true},"version_number":{"type":"integer","nullable":true},"version_label":{"type":"string","nullable":true},"subject_template":{"type":"string","nullable":true},"html_body_template":{"type":"string","nullable":true},"text_body_template":{"type":"string","nullable":true},"allowed_variables":{"type":"array","items":{"type":"string"}}},"required":["template_id","version_id","version_number","version_label","subject_template","html_body_template","text_body_template","allowed_variables"],"additionalProperties":false}},"required":["object","email_type","subject","html_body","text_body","is_sample","provenance"],"additionalProperties":false},"SchedulingReadinessResponse":{"anyOf":[{"type":"object","properties":{"ready":{"type":"boolean","enum":[true]}},"required":["ready"],"additionalProperties":false,"description":"Session is ready to be scheduled."},{"type":"object","properties":{"blocker_code":{"type":"string","enum":["INTERVIEWER_ASSIGNMENT_REQUIRED","INTERVIEWER_ASSIGNMENT_AMBIGUOUS","SCHEDULER_INTEGRATION_REQUIRED","SCHEDULER_WEBHOOK_SETUP_REQUIRED","SCHEDULER_EVENT_TYPE_MAPPING_MISSING","INTERVIEW_PLAN_NOT_FOUND","INTERVIEW_PLAN_AMBIGUOUS","INTERVIEW_PLAN_LINEAGE_MISMATCH","ROUND_ALREADY_SCHEDULED"],"description":"Stable machine-readable blocker code."},"blocker_message":{"type":"string","description":"Human-readable explanation of the blocker."},"blocker_metadata":{"type":"object","additionalProperties":{},"description":"Free-form structured metadata describing the blocker. Shape varies by `blocker_code`: `INTERVIEWER_ASSIGNMENT_REQUIRED` → `{ interview_session_id }`; `INTERVIEWER_ASSIGNMENT_AMBIGUOUS` → `{ interview_session_id, candidate_count }`; `SCHEDULER_INTEGRATION_REQUIRED` → `{ interviewer_user_id }`; `SCHEDULER_WEBHOOK_SETUP_REQUIRED` → `{ interviewer_user_id, provider }`; `SCHEDULER_EVENT_TYPE_MAPPING_MISSING` → `{ interviewer_user_id, provider, integration_id, interview_duration_minutes, mapping_key, settings_url }`; `INTERVIEW_PLAN_NOT_FOUND` → safe application/job/session context; `INTERVIEW_PLAN_AMBIGUOUS` → safe application/job context and candidate plan count; `INTERVIEW_PLAN_LINEAGE_MISMATCH` → safe application/job context, plan source, and linked-plan job context; `ROUND_ALREADY_SCHEDULED` → `{ interview_session_id, interview_id, booking_status }`, returned when the round already holds a confirmed booking (`booked` or `rescheduled`). Cancel the existing booking first. Rounds that are unscheduled, cancelled, or already have an outstanding link (`link_sent`) are not blocked -- each call still generates a fresh scheduling link. Missing event-type mapping metadata is safe to show to operators and points the assigned interviewer to `/admin/integrations/scheduling`. Plan-lineage blockers do not include interview sequences, provider secrets, OAuth tokens, Vault ids, or raw provider payloads."},"ready":{"type":"boolean","enum":[false]}},"required":["blocker_code","blocker_message","blocker_metadata","ready"],"additionalProperties":false,"description":"Session is not ready; `blocker_code` identifies the recovery flow."}],"description":"Discriminated readiness response. `ready: true` carries no extra fields; `ready: false` carries a structured blocker envelope."},"SchedulingGenerateLinkResponse":{"type":"object","properties":{"scheduling_link":{"type":"string","description":"Provider-rendered scheduling URL. Treat as opaque; do not parse."},"provider":{"type":"string","enum":["calcom","calendly"],"description":"Underlying provider that minted the link."},"expires_at":{"type":"string","description":"ISO-8601 UTC timestamp at which the corresponding `scheduling_link_tokens` row expires (30-day TTL)."},"link_id":{"type":"string","description":"Display id of the `scheduling_link_tokens` row backing this link. Use for out-of-band revocation lookups."}},"required":["scheduling_link","provider","expires_at","link_id"],"additionalProperties":false,"description":"Provider-agnostic success envelope for `scheduling.generate_link`. Each call mints a fresh link; previous links remain valid until their TTL expires."},"SchedulingCancelResponse":{"type":"object","properties":{"outcome":{"type":"string","enum":["cancelled","already_cancelled"],"description":"`already_cancelled` means the round was already cancelled. The idempotent side effects (link invalidation, calendar cancel) are re-applied, but no provider call, candidate email, or `scheduling.session_cancelled` event is produced."},"interview_session_id":{"type":"string","description":"Display id, e.g. `is_<base32>`."},"previous_booking_status":{"type":"string","nullable":true,"description":"`booking_status` as it stood before this call wrote anything."},"provider_cancel":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["made"]},"outcome":{"type":"string","enum":["cancelled","already_cancelled"],"description":"`already_cancelled` means the provider reported the booking was already gone, confirmed by re-reading the booking's own status."},"provider":{"type":"string","enum":["calcom","calendly"]}},"required":["status","outcome","provider"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["skipped"]},"skip_reason":{"type":"string","enum":["side_effects_suppressed","skip_provider_requested","no_provider_booking","no_external_booking","session_already_cancelled"]}},"required":["status","skip_reason"],"additionalProperties":false}],"description":"Whether the scheduling provider's booking was cancelled, and if not, why the call was skipped."},"candidate_email":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["sent","drafted","scheduled"]}},"required":["status"],"additionalProperties":false,"description":"The cancellation email was handed to the sending provider."},{"type":"object","properties":{"status":{"type":"string","enum":["skipped"]},"skip_reason":{"type":"string","enum":["provider_notifies_candidate","link_sent_no_booking","side_effects_suppressed","session_already_cancelled","reserved_test_recipient","candidate_email_missing","no_matching_rule"]}},"required":["status","skip_reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["email_not_sent"]},"reason_code":{"type":"string","description":"Why the send failed, e.g. `sender_default_missing`. A draft row and an email-send issue are recorded for follow-up."},"sender_resolution_type":{"type":"string","description":"Which sender rule was applied: `org_shared`, `owner`, `job_hiring_manager`, or `override`."}},"required":["status","reason_code","sender_resolution_type"],"additionalProperties":false,"description":"The cancel succeeded but the candidate was NOT told. Treat as actionable: the round is cancelled and the candidate still expects to attend."}],"description":"Outcome of the candidate cancellation email. Sent only for manually scheduled rounds; provider-booked rounds rely on the provider's own cancellation notice."},"suppressed":{"type":"object","properties":{"reason_code":{"type":"string","enum":["sample_data_side_effect_suppressed"]},"reason":{"type":"string","enum":["sample_data","partition_unknown"]}},"required":["reason_code","reason"],"additionalProperties":false,"nullable":true,"description":"Non-null when the session is sample data or its partition could not be determined. The local cancel still happens; the provider call and the candidate email are suppressed and no event is emitted."},"calendar_sync_ok":{"type":"boolean","description":"Whether the calendar orchestrator completed its cancel. `false` is not a failure of the cancel itself — the booking_status write has already committed — and is common, since most orgs have no calendar integration connected."}},"required":["outcome","interview_session_id","previous_booking_status","provider_cancel","candidate_email","suppressed","calendar_sync_ok"],"additionalProperties":false,"description":"Success envelope for `scheduling.cancel`. The cancel itself succeeded; `candidate_email` and `suppressed` are markers annotating an otherwise successful cancel and never change the status code."},"SchedulingCancelRefusalEnvelope":{"type":"object","properties":{"outcome":{"type":"string","enum":["invalid_source_state","lifecycle_state_locked","provider_cancel_failed"],"description":"Stable refusal code. `invalid_source_state`: nothing is scheduled to cancel. `lifecycle_state_locked`: the interview has already started or finished. `provider_cancel_failed`: the provider rejected the cancellation — no session state was changed, so the call is safe to retry, or resend with `skip_provider` to cancel in Yardstick only."},"message":{"type":"string","description":"Human-readable copy. Do not parse; branch on `outcome`."},"booking_status":{"type":"string","nullable":true},"session_status":{"type":"string","nullable":true},"provider_failure_code":{"type":"string","nullable":true,"description":"Provider-factory or adapter failure code when one is known, e.g. `integration_not_found`."}},"required":["outcome","message","booking_status","session_status","provider_failure_code"],"additionalProperties":false,"description":"Structured 409 refusal envelope for `scheduling.cancel`. Distinct from `SchedulingBlockerEnvelope`: readiness/generate_link blockers describe a setup gap, whereas these describe the round's own state. Nothing was written when this is returned."},"InterviewSessionEnsureResponse":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `is_<base32>`."},"object":{"type":"string","enum":["interview_session"]},"application_id":{"type":"string","description":"Display id, e.g. `app_<base32>`."},"opportunity_id":{"type":"string","description":"Display id, e.g. `opp_<base32>`."},"interview_plan_id":{"type":"string","description":"Display id of the application's interview plan, e.g. `ipd_<base32>`."},"round":{"type":"object","properties":{"id":{"type":"string","description":"Stable interview-plan round id."},"title":{"type":"string","description":"Trusted stored round title."}},"required":["id","title"],"additionalProperties":false},"status":{"type":"string","description":"Current interview session status."},"interview_version_id":{"type":"string","nullable":true,"description":"UUID of the assigned interview version when one is available."},"livemode":{"type":"boolean"},"created":{"type":"boolean","description":"True when the ensure call created a new session row."},"reused":{"type":"boolean","description":"True when the ensure call reused an existing session row."}},"required":["id","object","application_id","opportunity_id","interview_plan_id","round","status","interview_version_id","livemode","created","reused"],"additionalProperties":false,"description":"Redacted setup envelope for an ensured interview session. It intentionally excludes scheduling links, meeting links, provider ids, candidate notes, interviewer emails, and hidden scheduling metadata."},"InterviewSessionAssignInterviewerResponse":{"type":"object","properties":{"object":{"type":"string","enum":["interview_session_interviewer"]},"interviewer_user_id":{"type":"string","description":"Raw UUID of the assigned interviewer."},"is_primary":{"type":"boolean","description":"Whether this interviewer is the primary assignment row."},"assigned_at":{"type":"string","description":"ISO-8601 UTC timestamp from the assignment row."},"interview_session_id":{"type":"string","description":"Display id of the interview session, e.g. `is_<base32>`."},"created":{"type":"boolean","description":"True when this call inserted the assignment row."},"reused":{"type":"boolean","description":"True when the interviewer was already assigned."},"scheduling_ready":{"type":"boolean","description":"True only when the session has exactly one interviewer."},"scheduling_blocker":{"type":"string","enum":["INTERVIEWER_ASSIGNMENT_REQUIRED","INTERVIEWER_ASSIGNMENT_AMBIGUOUS"],"description":"Scheduling blocker derived from the current interviewer assignment rows.","nullable":true},"interviewer_email":{"anyOf":[{"type":"object","properties":{"status":{"type":"string","enum":["sent","already_sent"]}},"required":["status"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["skipped"]},"skip_reason":{"type":"string","enum":["opted_out","self_assignment","side_effects_suppressed","not_allowed"]}},"required":["status","skip_reason"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["email_not_sent"]},"reason_code":{"type":"string","enum":["interviewer_email_missing","send_failed","notify_error"]}},"required":["status","reason_code"],"additionalProperties":false}],"description":"Safe notification outcome; assignment succeeds even when email is not sent."},"suppressed":{"type":["object","null"],"properties":{"reason_code":{"type":"string","enum":["sample_data_side_effect_suppressed"]},"reason":{"type":"string","enum":["sample_data","partition_unknown"]}},"required":["reason_code","reason"],"additionalProperties":false,"description":"Non-null for sample data or unknown partition; no interview link is minted and no email is sent."},"user_tasks":{"type":"object","properties":{"interview_session_task_created":{"type":"boolean","description":"Whether the trigger-created interview-session task exists."},"application_interview_task_created":{"type":"boolean","description":"Whether the trigger-created application-interview task exists."}},"required":["interview_session_task_created","application_interview_task_created"],"additionalProperties":false,"description":"Observed user-task trigger side effects after assignment."},"audit_id":{"type":"string","description":"Display id of the audit log row."},"event_id":{"type":"string","description":"Display id of the API event row."}},"required":["object","interviewer_user_id","is_primary","assigned_at","interview_session_id","created","reused","scheduling_ready","scheduling_blocker","interviewer_email","suppressed","user_tasks","audit_id","event_id"],"additionalProperties":false,"description":"Success envelope for assigning an interviewer to an interview session."},"InterviewSessionInterviewerListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"interview_session_id":{"type":"string","description":"Display id of the interview session, e.g. `is_<base32>`."},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["interview_session_interviewer"]},"interviewer_user_id":{"type":"string","description":"Raw UUID of the assigned interviewer."},"is_primary":{"type":"boolean","description":"Whether this interviewer is the primary assignment row."},"assigned_at":{"type":"string","description":"ISO-8601 UTC timestamp from the assignment row."}},"required":["object","interviewer_user_id","is_primary","assigned_at"],"additionalProperties":false,"description":"Redacted interviewer assignment row for an interview session."},"description":"Assigned interviewers, primary first then assigned_at ascending."}},"required":["object","interview_session_id","data"],"additionalProperties":false,"description":"List envelope for interview session interviewer assignments."},"AssignableInterviewer":{"type":"object","properties":{"id":{"type":"string","description":"Display id of the organization member, e.g. `usr_<base32>`. Decode it to the raw UUID that `assign_interviewer` accepts."},"object":{"type":"string","enum":["user"]},"name":{"type":"string","nullable":true,"description":"Full name from the member profile, or null when unset."},"email":{"type":"string","nullable":true,"description":"Email from the member profile, or null when unset."}},"required":["id","object","name","email"],"additionalProperties":false,"description":"An organization member who can be assigned to an interview session as an interviewer."},"InterviewSessionUnassignInterviewerResponse":{"type":"object","properties":{"object":{"type":"string","enum":["interview_session_interviewer"]},"interview_session_id":{"type":"string","description":"Display id of the interview session, e.g. `is_<base32>`."},"interviewer_user_id":{"type":"string","description":"Raw UUID of the interviewer requested for removal."},"removed":{"type":"integer","minimum":0,"maximum":1,"description":"1 when a row was deleted; 0 for an idempotent no-op."},"scheduling_ready":{"type":"boolean","description":"True only when the session has exactly one interviewer."},"scheduling_blocker":{"type":"string","enum":["INTERVIEWER_ASSIGNMENT_REQUIRED","INTERVIEWER_ASSIGNMENT_AMBIGUOUS"],"description":"Scheduling blocker derived from the current interviewer assignment rows.","nullable":true},"user_tasks":{"type":"object","properties":{"interview_session_task_removed":{"type":"boolean","description":"Whether the interview-session task was removed."},"application_interview_task_removed":{"type":"boolean","description":"Whether the application-interview task was removed."}},"required":["interview_session_task_removed","application_interview_task_removed"],"additionalProperties":false,"description":"Observed user-task trigger side effects after unassignment."},"audit_id":{"type":"string","description":"Display id of the audit log row."},"event_id":{"type":"string","description":"Display id of the API event row."}},"required":["object","interview_session_id","interviewer_user_id","removed","scheduling_ready","scheduling_blocker","user_tasks","audit_id","event_id"],"additionalProperties":false,"description":"Success envelope for unassigning an interviewer from an interview session."},"SchedulingBlockerEnvelope":{"type":"object","properties":{"blocker_code":{"type":"string","enum":["INTERVIEWER_ASSIGNMENT_REQUIRED","INTERVIEWER_ASSIGNMENT_AMBIGUOUS","SCHEDULER_INTEGRATION_REQUIRED","SCHEDULER_WEBHOOK_SETUP_REQUIRED","SCHEDULER_EVENT_TYPE_MAPPING_MISSING","INTERVIEW_PLAN_NOT_FOUND","INTERVIEW_PLAN_AMBIGUOUS","INTERVIEW_PLAN_LINEAGE_MISMATCH","ROUND_ALREADY_SCHEDULED"],"description":"Stable machine-readable blocker code."},"blocker_message":{"type":"string","description":"Human-readable explanation of the blocker."},"blocker_metadata":{"type":"object","additionalProperties":{},"description":"Free-form structured metadata describing the blocker. Shape varies by `blocker_code`: `INTERVIEWER_ASSIGNMENT_REQUIRED` → `{ interview_session_id }`; `INTERVIEWER_ASSIGNMENT_AMBIGUOUS` → `{ interview_session_id, candidate_count }`; `SCHEDULER_INTEGRATION_REQUIRED` → `{ interviewer_user_id }`; `SCHEDULER_WEBHOOK_SETUP_REQUIRED` → `{ interviewer_user_id, provider }`; `SCHEDULER_EVENT_TYPE_MAPPING_MISSING` → `{ interviewer_user_id, provider, integration_id, interview_duration_minutes, mapping_key, settings_url }`; `INTERVIEW_PLAN_NOT_FOUND` → safe application/job/session context; `INTERVIEW_PLAN_AMBIGUOUS` → safe application/job context and candidate plan count; `INTERVIEW_PLAN_LINEAGE_MISMATCH` → safe application/job context, plan source, and linked-plan job context; `ROUND_ALREADY_SCHEDULED` → `{ interview_session_id, interview_id, booking_status }`, returned when the round already holds a confirmed booking (`booked` or `rescheduled`). Cancel the existing booking first. Rounds that are unscheduled, cancelled, or already have an outstanding link (`link_sent`) are not blocked -- each call still generates a fresh scheduling link. Missing event-type mapping metadata is safe to show to operators and points the assigned interviewer to `/admin/integrations/scheduling`. Plan-lineage blockers do not include interview sequences, provider secrets, OAuth tokens, Vault ids, or raw provider payloads."}},"required":["blocker_code","blocker_message","blocker_metadata"],"additionalProperties":false,"description":"Structured 409 blocker envelope for scheduling actions. The same shape is reused inside the readiness response under `{ ready: false }`."},"ApplicationStatusTransitionResponse":{"anyOf":[{"type":"object","properties":{"is_candidate":{"type":"boolean","description":"Explicitly admitted to the interview process; Review Applications and Candidates are mutually exclusive per application."},"candidate_admission_id":{"type":"string","format":"uuid","nullable":true,"description":"Raw current admission UUID, required as expected_admission_id when undoing."},"candidate_admitted_at":{"type":"string","nullable":true},"candidate_admission_origin":{"type":"string","nullable":true},"candidate_activity_started_at":{"type":"string","nullable":true,"description":"Non-null after durable candidate activity; undo is then unavailable."},"id":{"type":"string","description":"Display id, e.g. `app_<base32>`"},"object":{"type":"string","enum":["application"]},"person_id":{"type":"string","description":"Canonical `per_...` person id."},"status":{"type":"string"},"stage":{"type":"string","description":"Deprecated free-form stage label. Status transitions never change it; read `pipeline_stage_id` for the pipeline position."},"pipeline_stage_id":{"type":"string","nullable":true,"description":"Display id (`pst_<base32>`) of the configured pipeline stage (board column) the application sits in; every status transition moves it to the stage mapped to the new status. Null when no configured stage is assigned."},"job_id":{"type":"string","nullable":true,"description":"Canonical `job_...` Job id when the application is linked to a Job; null for legacy or unlinked applications."},"job_posting_id":{"type":"string","nullable":true},"source":{"type":"object","properties":{"token_id":{"type":"string","nullable":true},"label":{"type":"string","nullable":true}},"required":["token_id","label"],"additionalProperties":false},"livemode":{"type":"boolean"},"created":{"type":"string","nullable":true},"updated":{"type":"string","nullable":true},"archived_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC; non-null when the application has been archived."},"archived_reason":{"type":"string","nullable":true,"description":"Free-text archive reason captured at archive time; nullable."},"transition":{"type":"object","properties":{"idempotent":{"type":"boolean"},"mutated":{"type":"boolean"},"execution_mode":{"type":"string","enum":["direct_write"]},"pipeline_stage_id":{"type":"string","description":"Display id (`pst_<base32>`) of the configured pipeline stage the move resolved to and wrote. Present on a mutating transition (direct write or approval bind). The status is derived from this stage's mapped status, so a request may target the move either by `status` or by `pipeline_stage_id`."}},"required":["idempotent","mutated"],"additionalProperties":false}},"required":["is_candidate","candidate_admission_id","candidate_admitted_at","candidate_admission_origin","candidate_activity_started_at","id","object","person_id","status","stage","pipeline_stage_id","job_id","job_posting_id","source","livemode","created","updated","archived_at","archived_reason","transition"],"additionalProperties":false,"description":"Application response returned for idempotent or direct status transitions."},{"type":"object","properties":{"object":{"type":"string","enum":["application_status_transition"]},"action":{"type":"string","enum":["application.transition_status"]},"application_id":{"type":"string"},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["application"]},"id":{"type":"string"}},"required":["type","id"],"additionalProperties":false},"execution_mode":{"type":"string","enum":["direct_write","approval_required","blocked_until_verified"]},"approval_required":{"type":"boolean"},"blocked":{"type":"boolean"},"action_gate_blocked":{"type":"boolean","description":"Present and `true` when an unmet per-stage action gate blocked the move. A distinct discriminator from approval/validity blocks: it is returned (HTTP 409) BEFORE any approval preview, so a gated move never reaches the approval ceremony while the gate is unmet. Pair with `gate` for the machine-readable reason."},"mutated":{"type":"boolean"},"current_status":{"type":"string"},"proposed_status":{"type":"string"},"proposed_pipeline_stage_id":{"type":"string","description":"The pipeline stage (`pst_` id, the board column) the application will move to when the approved transition is bound. Display-only on the approval preview; the legacy `stage` label does not move."},"reason":{"type":"string","nullable":true},"gate":{"type":"object","properties":{"type":{"type":"string","description":"The unmet gate type, e.g. `scorecard_submitted`."},"reason":{"type":"string","description":"Human-readable, agent-actionable explanation, e.g. `Needs a submitted scorecard for the current round`."}},"required":["type","reason"],"additionalProperties":false,"description":"Detail of the unmet action gate, present only alongside `action_gate_blocked: true`."},"approval":{"type":"object","properties":{"gate":{"type":"string"},"reason":{"type":"string"},"preview_required":{"type":"array","items":{"type":"string"}},"binding":{"type":"object","properties":{"required_fields":{"type":"array","items":{"type":"string"}},"approved_action_key":{"type":"string","enum":["application.transition_status"]},"resource_version_precondition":{"type":"string","nullable":true}},"required":["required_fields","approved_action_key","resource_version_precondition"],"additionalProperties":false}},"required":["gate","reason","preview_required","binding"],"additionalProperties":false},"required_scopes":{"type":"array","items":{"type":"string"}}},"required":["object","action","execution_mode","mutated","current_status","proposed_status"],"additionalProperties":false,"description":"Application status-transition action envelope returned when a transition requires approval, is blocked by an unmet action gate (`action_gate_blocked`), or is blocked pending verification."}],"description":"Application status-transition action response. Direct non-terminal transitions may mutate; sensitive or unverified transitions return approval-required or blocked envelopes."},"StatusEmailApprovalPocPreview":{"type":"object","properties":{"object":{"type":"string","enum":["application_status_email_approval_poc_preview"]},"action_key":{"type":"string","enum":["application.status_email_approval_poc"]},"resource_type":{"type":"string","enum":["application"]},"resource_id":{"type":"string"},"mutated":{"type":"boolean","enum":[false]},"application":{"type":"object","properties":{"id":{"type":"string"},"current_status":{"type":"string","enum":["Interviewing"]},"target_status":{"type":"string","enum":["Offer"]},"mode":{"type":"string","enum":["live","test"]},"livemode":{"type":"boolean"}},"required":["id","current_status","target_status","mode","livemode"],"additionalProperties":false},"candidate":{"type":"object","properties":{"id":{"type":"string"},"display_name":{"type":"string","nullable":true}},"required":["id","display_name"],"additionalProperties":false},"person":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string"}},"required":["id","email"],"additionalProperties":false},"job":{"type":"object","properties":{"id":{"type":"string","nullable":true},"job_posting_id":{"type":"string","nullable":true}},"required":["id","job_posting_id"],"additionalProperties":false},"current_state":{"type":"object","additionalProperties":{}},"proposed_state":{"type":"object","additionalProperties":{}},"status_side_effect":{"type":"object","additionalProperties":{}},"email_side_effect":{"type":"object","additionalProperties":{}},"recipient":{"type":"object","additionalProperties":{}},"sender_state":{"type":"object","additionalProperties":{}},"template":{"type":"object","additionalProperties":{}},"template_version":{"type":"object","additionalProperties":{}},"template_provenance":{"type":"object","properties":{"source":{"type":"string"},"prompt_redacted":{"type":"boolean","enum":[true]},"provider_payload_redacted":{"type":"boolean","enum":[true]}},"required":["source","prompt_redacted","provider_payload_redacted"],"additionalProperties":true},"required_scopes":{"type":"array","items":{"type":"string","enum":["applications:read","applications:write","applications:transition_status","applications:offer","communications:read","communications:write"]}},"idempotency_key":{"type":"string"},"resource_version_precondition":{"type":"string","nullable":true},"preview_hash":{"type":"string"},"input_hash":{"type":"string"},"approval_required":{"type":"boolean","enum":[true]},"approval":{"type":"object","properties":{"gate":{"type":"string"},"preview_required":{"type":"array","items":{"type":"string"}},"binding":{"type":"object","properties":{"required_fields":{"type":"array","items":{"type":"string","enum":["preview_hash","approved_action_key","approved_input_hash","approved_idempotency_key","resource_version_precondition"]}},"approved_action_key":{"type":"string","enum":["application.status_email_approval_poc"]},"preview_hash":{"type":"string"},"approved_input_hash":{"type":"string"},"approved_idempotency_key":{"type":"string"},"resource_version_precondition":{"type":"string","nullable":true}},"required":["required_fields","approved_action_key","preview_hash","approved_input_hash","approved_idempotency_key","resource_version_precondition"],"additionalProperties":false}},"required":["gate","preview_required","binding"],"additionalProperties":false},"audit_event_plan":{"type":"object","properties":{"bind_event_type":{"type":"string","enum":["application.status_email_approval_poc.bound"]},"denied_event_type":{"type":"string","enum":["application.status_email_approval_poc.denied"]},"preview_audit_write":{"type":"boolean","enum":[false]}},"required":["bind_event_type","denied_event_type","preview_audit_write"],"additionalProperties":false},"api_event_plan":{"type":"object","properties":{"preview_event_type":{"type":"string","enum":["application.status_email_approval_poc.previewed"]},"bind_event_type":{"type":"string","enum":["application.status_email_approval_poc.bound"]},"preview_event_write":{"type":"boolean","enum":[false]}},"required":["preview_event_type","bind_event_type","preview_event_write"],"additionalProperties":false},"dashboard_read_back":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"supported_query_filters":{"type":"array","items":{"type":"string"}},"use":{"type":"string"},"availability":{"type":"string"}},"required":["surface","path"],"additionalProperties":false,"description":"Read-back pointer for the fixed status/email approval POC."}},"api_read_back":{"type":"array","items":{"type":"object","properties":{"surface":{"type":"string"},"method":{"type":"string"},"path":{"type":"string"},"supported_query_filters":{"type":"array","items":{"type":"string"}},"use":{"type":"string"},"availability":{"type":"string"}},"required":["surface","path"],"additionalProperties":false,"description":"Read-back pointer for the fixed status/email approval POC."}},"poc_boundary":{"type":"string"},"request_id":{"type":"string"}},"required":["object","action_key","resource_type","resource_id","mutated","application","candidate","person","job","current_state","proposed_state","status_side_effect","email_side_effect","recipient","sender_state","template","template_version","template_provenance","required_scopes","idempotency_key","resource_version_precondition","preview_hash","input_hash","approval_required","approval","audit_event_plan","api_event_plan","dashboard_read_back","api_read_back","poc_boundary","request_id"],"additionalProperties":false,"description":"Preview response for the fixed applications-owned status/email approval POC. It is mutation-free and only supports Interviewing -> Offer, email_type=offer, decision=review_edit."},"StatusEmailApprovalPocBind":{"type":"object","properties":{"object":{"type":"string","enum":["application_status_email_approval_poc_bind"]},"action_key":{"type":"string","enum":["application.status_email_approval_poc"]},"resource_type":{"type":"string","enum":["application"]},"resource_id":{"type":"string"},"mutated":{"type":"boolean"},"reused":{"type":"boolean"},"application":{"type":"object","properties":{"id":{"type":"string"},"previous_status":{"type":"string","enum":["Interviewing"]},"status":{"type":"string","enum":["Offer"]},"mode":{"type":"string","enum":["live","test"]},"livemode":{"type":"boolean"}},"required":["id","previous_status","status","mode","livemode"],"additionalProperties":false},"status_transition":{"type":"object","properties":{"from_status":{"type":"string","enum":["Interviewing"]},"to_status":{"type":"string","enum":["Offer"]},"application_status_change_id":{"type":"string"},"idempotent":{"type":"boolean"}},"required":["from_status","to_status","application_status_change_id","idempotent"],"additionalProperties":false},"candidate_email_decision":{"type":"object","properties":{"decision_intent_id":{"type":"string"},"application_status_change_id":{"type":"string"},"email_type":{"type":"string","enum":["offer"]},"decision":{"type":"string","enum":["review_edit"]},"effect":{"type":"string","enum":["draft_for_review","suppressed"]},"autonomous_send":{"type":"boolean","enum":[false]},"idempotency_key":{"type":"string"}},"required":["decision_intent_id","application_status_change_id","email_type","decision","effect","autonomous_send","idempotency_key"],"additionalProperties":false},"draft":{"type":"object","properties":{"id":{"type":"string","nullable":true},"status":{"type":"string"},"existing":{"type":"boolean"},"processed_at":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true}},"required":["id","status","existing","processed_at","reason"],"additionalProperties":false,"nullable":true},"side_effects":{"type":"array","items":{"type":"string"}},"request_id":{"type":"string"}},"required":["object","action_key","resource_type","resource_id","mutated","reused","application","status_transition","candidate_email_decision","draft","side_effects","request_id"],"additionalProperties":false,"description":"Bind response for the fixed applications-owned status/email approval POC. A successful bind applies one approved status transition and either creates a reviewed-offer draft or suppresses that draft when a current formal offer owns delivery; same-key replay reports reused/idempotent without duplicating side effects."},"EmailDraft":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["email_draft"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","scorecard_nudge","scorecard_escalation","decision_brief","prospect_outreach","candidate_follow_up","interview_cancellation"]},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"],"nullable":true},"candidate_follow_through":{"type":"object","properties":{"built_in_agent":{"type":"object","properties":{"key":{"type":"string","enum":["candidate-follow-through"]},"label":{"type":"string","enum":["Keep candidates informed"]}},"required":["key","label"],"additionalProperties":false},"review_state":{"type":"string","enum":["reviewable","invalidated"]},"invalidation_reason":{"type":"string","enum":["application_changed","session_changed","recipient_changed","communication_changed","configuration_changed","template_changed","feature_disabled","cycle_changed"],"nullable":true},"send_available":{"type":"boolean"},"source":{"type":"object","properties":{"last_interview_at":{"type":"string","nullable":true},"last_interview_date":{"type":"string","nullable":true}},"required":["last_interview_at","last_interview_date"],"additionalProperties":false},"personalization":{"type":"object","properties":{"source":{"type":"string","enum":["model","deterministic"]},"fallback_used":{"type":"boolean"}},"required":["source","fallback_used"],"additionalProperties":false}},"required":["built_in_agent","review_state","invalidation_reason","send_available","source","personalization"],"additionalProperties":false}},"required":["id","object","email_type","delivery_mode"],"additionalProperties":true},"EmailDraftListResponse":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["email_draft"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","scorecard_nudge","scorecard_escalation","decision_brief","prospect_outreach","candidate_follow_up","interview_cancellation"]},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"],"nullable":true},"candidate_follow_through":{"type":"object","properties":{"built_in_agent":{"type":"object","properties":{"key":{"type":"string","enum":["candidate-follow-through"]},"label":{"type":"string","enum":["Keep candidates informed"]}},"required":["key","label"],"additionalProperties":false},"review_state":{"type":"string","enum":["reviewable","invalidated"]},"invalidation_reason":{"type":"string","enum":["application_changed","session_changed","recipient_changed","communication_changed","configuration_changed","template_changed","feature_disabled","cycle_changed"],"nullable":true},"send_available":{"type":"boolean"},"source":{"type":"object","properties":{"last_interview_at":{"type":"string","nullable":true},"last_interview_date":{"type":"string","nullable":true}},"required":["last_interview_at","last_interview_date"],"additionalProperties":false},"personalization":{"type":"object","properties":{"source":{"type":"string","enum":["model","deterministic"]},"fallback_used":{"type":"boolean"}},"required":["source","fallback_used"],"additionalProperties":false}},"required":["built_in_agent","review_state","invalidation_reason","send_available","source","personalization"],"additionalProperties":false}},"required":["id","object","email_type","delivery_mode"],"additionalProperties":true}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false},"EmailDraftPreview":{"type":"object","properties":{"object":{"type":"string","enum":["email_draft_preview"]},"draft_id":{"type":"string"}},"required":["object","draft_id"],"additionalProperties":true},"EmailDraftHistory":{"type":"object","properties":{"object":{"type":"string","enum":["email_draft_history"]},"draft_id":{"type":"string"},"data":{"type":"array","items":{"type":"object","additionalProperties":{}}}},"required":["object","draft_id","data"],"additionalProperties":false},"EmailDraftUpdateRequest":{"type":"object","properties":{"subject":{"type":"string","minLength":1},"html_body":{"type":"string","minLength":1},"text_body":{"type":"string","nullable":true},"from_name":{"type":"string","nullable":true},"reply_to":{"type":"string","nullable":true},"requested_sender_identity_id":{"type":"string","format":"uuid","nullable":true}},"additionalProperties":false},"EmailSenderSettings":{"type":"object","properties":{"object":{"type":"string","enum":["email_sender_settings"]},"livemode":{"type":"boolean"},"connections":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["email_sender_connection"]},"provider_connection_id":{"type":"string"},"user_id":{"type":"string","nullable":true},"provider":{"type":"string"},"status":{"type":"string"},"provider_account_email":{"type":"string","nullable":true},"provider_account_name":{"type":"string","nullable":true},"scopes_granted":{"type":"array","items":{"type":"string"}},"expires_at":{"type":"string","nullable":true},"last_refresh_at":{"type":"string","nullable":true},"last_error_code":{"type":"string","nullable":true},"sender_identity_sync_status":{"type":"string"},"sender_identity_sync_error_code":{"type":"string","nullable":true},"sender_identity_sync_last_attempted_at":{"type":"string","nullable":true},"sender_identity_sync_last_synced_at":{"type":"string","nullable":true},"identity_count":{"type":"integer","minimum":0},"available_identity_count":{"type":"integer","minimum":0},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","provider_connection_id","user_id","provider","status","provider_account_email","provider_account_name","scopes_granted","expires_at","last_refresh_at","last_error_code","sender_identity_sync_status","sender_identity_sync_error_code","sender_identity_sync_last_attempted_at","sender_identity_sync_last_synced_at","identity_count","available_identity_count","created_at","updated_at"],"additionalProperties":false}},"identities":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["email_sender_identity"]},"id":{"type":"string"},"user_id":{"type":"string","nullable":true},"provider_connection_id":{"type":"string"},"provider":{"type":"string"},"identity_type":{"type":"string"},"email":{"type":"string"},"display_name":{"type":"string","nullable":true},"status":{"type":"string"},"validation_error_code":{"type":"string","nullable":true},"validated_at":{"type":"string","nullable":true},"unavailable_at":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","user_id","provider_connection_id","provider","identity_type","email","display_name","status","validation_error_code","validated_at","unavailable_at","created_at","updated_at"],"additionalProperties":false}},"defaults":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["email_sender_default"]},"id":{"type":"string","nullable":true},"email_type":{"type":"string"},"default_sender_type":{"type":"string"},"org_shared_sender_identity_id":{"type":"string","nullable":true},"org_shared_sender_email":{"type":"string","nullable":true},"org_shared_sender_display_name":{"type":"string","nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","email_type","default_sender_type","org_shared_sender_identity_id","org_shared_sender_email","org_shared_sender_display_name","created_at","updated_at"],"additionalProperties":false}},"queue":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["email_sender_queue_item"]},"id":{"type":"string"},"email_draft_id":{"type":"string","nullable":true},"application_id":{"type":"string","nullable":true},"email_type":{"type":"string"},"queue_status":{"type":"string"},"sender_resolution_type":{"type":"string","nullable":true},"requested_sender_identity_id":{"type":"string","nullable":true},"resolved_sender_identity_id":{"type":"string","nullable":true},"reason_code":{"type":"string","nullable":true},"attempts_count":{"type":"integer","minimum":0},"last_attempt_at":{"type":"string","nullable":true},"last_error_code":{"type":"string","nullable":true},"next_attempt_at":{"type":"string","nullable":true},"latest_attempt_status":{"type":"string","nullable":true},"latest_attempt_provider":{"type":"string","nullable":true},"latest_attempt_error_code":{"type":"string","nullable":true},"latest_attempt_at":{"type":"string","nullable":true},"diagnostic_schema_version":{"type":"integer","exclusiveMinimum":true,"minimum":0,"nullable":true},"failure_phase":{"type":"string","enum":["default_missing","job_resolution_failed","identity_unavailable","provider_connection_unavailable","token_unavailable","provider_send_failed","system_fallback_disallowed","system_fallback_failed"],"nullable":true},"selected_transport":{"type":"string","enum":["google","microsoft","resend","none"],"nullable":true},"fallback_eligible":{"type":"boolean","nullable":true},"safe_next_action":{"type":"string","enum":["configure_default_sender","assign_job_sender","review_sender_identity","reconnect_provider","configure_customer_sender","configure_system_sender","retry_after_provider_recovery"],"nullable":true},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["object","id","email_draft_id","application_id","email_type","queue_status","sender_resolution_type","requested_sender_identity_id","resolved_sender_identity_id","reason_code","attempts_count","last_attempt_at","last_error_code","next_attempt_at","latest_attempt_status","latest_attempt_provider","latest_attempt_error_code","latest_attempt_at","diagnostic_schema_version","failure_phase","selected_transport","fallback_eligible","safe_next_action","created_at","updated_at"],"additionalProperties":false,"description":"Redacted send-queue summary. Diagnostic fields are allowlisted summaries and never include raw metadata, recipient addresses, bodies, provider payloads, or secret material."}}},"required":["object","livemode","connections","identities","defaults","queue"],"additionalProperties":false},"Event":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `evt_<base32>`"},"object":{"type":"string","enum":["event"]},"type":{"type":"string","description":"Stable event type, e.g. `person.created`"},"created":{"type":"string","description":"ISO-8601 UTC"},"livemode":{"type":"boolean"},"api_version":{"type":"string","description":"Pinned API version (YYYY-MM-DD)"},"request_id":{"type":"string","nullable":true,"description":"Correlation id for the request that produced this event — the same value returned in that request's `X-Request-Id` response header. Null for events written before the id was recorded, and for events produced outside an API request."},"data":{"type":"object","additionalProperties":{}}},"required":["id","object","type","created","livemode","api_version","request_id","data"],"additionalProperties":false,"description":"Customer-facing audit event from the API event log."},"AuditLogEntry":{"type":"object","properties":{"id":{"type":"string","description":"Display id, e.g. `audit_<base32>`"},"object":{"type":"string","enum":["audit_log_entry"]},"created":{"type":"string"},"actor_token_id":{"type":"string","nullable":true},"action":{"type":"string"},"resource_type":{"type":"string"},"resource_id":{"type":"string","nullable":true},"resource_display_id":{"type":"string","nullable":true,"description":"The public display id of the audited resource — the same id the caller holds, e.g. `can_<base32>`. Null when the resource type has no public id namespace; no prefix is invented for one."},"changes":{"type":"object","additionalProperties":{}},"request_id":{"type":"string","nullable":true,"description":"Correlation id for the request that produced this entry — the same value returned in that request's `X-Request-Id` response header. Null for entries written before the id was recorded."},"authenticated_actor":{"type":"object","properties":{"kind":{"type":"string","enum":["platform_runtime"]},"principal_ref":{"type":"string"},"display_label":{"type":"string"},"principal_generation":{"type":"integer","exclusiveMinimum":true,"minimum":0},"credential_id":{"type":"string","format":"uuid"},"organization_display_id":{"type":"string","description":"Public organization display id, e.g. `org_<base32>`"},"execution_mode":{"type":"string","enum":["live","test","mode_neutral"]},"livemode":{"type":"boolean","nullable":true},"run_id":{"type":"integer","exclusiveMinimum":true,"minimum":0},"step_id":{"type":"integer","exclusiveMinimum":true,"minimum":0},"intent_id":{"type":"integer","exclusiveMinimum":true,"minimum":0},"idempotency_key":{"type":"string"},"operation_name":{"type":"string"},"department_read_mode":{"type":"string","enum":["none","explicit"]},"department_read_scope":{"type":"array","items":{"type":"string"}}},"required":["kind","principal_ref","display_label","principal_generation","credential_id","organization_display_id","execution_mode","livemode","run_id","step_id","intent_id","idempotency_key","operation_name","department_read_mode","department_read_scope"],"additionalProperties":false,"description":"Verified immutable platform-runtime lineage derived from the consumed credential and ledger context. It never contains the credential secret.","nullable":true},"authentication":{"type":"object","properties":{"state":{"type":"string","enum":["pre_auth","post_auth"]},"mechanism":{"type":"string","enum":["runtime_credential"]},"reason_code":{"type":"string","nullable":true},"claimed_subject":{"type":"object","properties":{"principal_ref":{"type":"string"},"verified":{"type":"boolean","enum":[false]}},"required":["principal_ref","verified"],"additionalProperties":false,"nullable":true}},"required":["state","mechanism","reason_code","claimed_subject"],"additionalProperties":false,"description":"Bounded runtime authentication evidence. A pre-auth row always has authenticated_actor=null and any claimed subject is explicitly unverified."},"outcome":{"type":"string","nullable":true},"reason":{"type":"string","nullable":true}},"required":["id","object","created","actor_token_id","action","resource_type","resource_id","resource_display_id","changes","request_id"],"additionalProperties":false,"description":"An audit log entry capturing an API-driven mutation (writes only). Human API-token rows retain the historical shape. Runtime rows add a bounded authentication object and a verified actor snapshot; pre-auth rows keep authenticated_actor null. The caller's org id is excluded — implicit from the bearer token and exposing it would leak an internal UUID."},"StagedBuilderActionResponse":{"type":"object","properties":{"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan_draft","interview_plan"]},"id":{"type":"string","nullable":true}},"required":["type","id"],"additionalProperties":false},"action":{"type":"string","enum":["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"]},"execution_mode":{"type":"string","enum":["draft_write","interactive_gate","validate_only","approval_required","blocked_until_verified"]},"approval":{"type":"object","properties":{"gate":{"type":"string","enum":["none","agent_confirmable","dashboard_required"]},"required":{"type":"boolean"},"reason":{"type":"string"}},"required":["gate","required","reason"],"additionalProperties":false},"stage":{"type":"string"},"data":{"type":"object","properties":{"status":{"type":"string","enum":["checkpointed","generated","generation_pending","validated","not_ready","unsupported_stage","approval_required","blocked"]},"message":{"type":"string"},"outcomes":{"type":"array","items":{"type":"object","additionalProperties":{}}},"competencies":{"type":"array","items":{"type":"object","additionalProperties":{}}},"job_skills":{"type":"array","items":{"type":"object","additionalProperties":{}}},"interview_sequence":{"type":"array","items":{"type":"object","additionalProperties":{}}},"questions_and_directions":{"type":"object","additionalProperties":{}},"behavioral_anchors":{"type":"object","additionalProperties":{}},"round_id":{"type":"string"},"questions":{"type":"array","items":{"type":"object","additionalProperties":{}}},"interviewer_directions":{"type":"string","nullable":true},"candidate_directions":{"type":"string","nullable":true},"pruned_behavioral_anchor_ids":{"type":"array","items":{"type":"string"},"description":"Item ids whose behavioral anchors were pruned because their competency was deleted in this request."},"pruned_question_round_ids":{"type":"array","items":{"type":"string"},"description":"Round ids whose questions and directions were pruned because the round was deleted in this request."},"generated_round_ids":{"type":"array","items":{"type":"string"}},"generated_competency_ids":{"type":"array","items":{"type":"string"}},"preview":{"type":"object","additionalProperties":{}},"affected_counts":{"type":"object","additionalProperties":{}},"audit":{"type":"object","properties":{"audit_id":{"type":"string"},"event_id":{"type":"string"},"audit_log":{"type":"string"},"api_event":{"type":"string"}},"required":["audit_log","api_event"],"additionalProperties":false}},"required":["status","message"],"additionalProperties":false},"checkpoint":{"type":"object","properties":{"stage":{"type":"string"},"version":{"type":"integer","minimum":0},"stage_versions":{"type":"object","additionalProperties":{}}},"required":["stage","version","stage_versions"],"additionalProperties":false},"validation":{"type":"object","properties":{"status":{"type":"string","enum":["not_evaluated","ready","blocked"]},"publish_ready":{"type":"boolean"},"blockers":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"next_action":{"type":"string"}},"required":["code","message"],"additionalProperties":false}},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"path":{"type":"string"},"next_action":{"type":"string"}},"required":["code","message"],"additionalProperties":false}}},"required":["status","publish_ready","blockers","warnings"],"additionalProperties":false},"next_actions":{"type":"array","items":{"type":"string","enum":["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"]}},"web_url":{"type":"string","nullable":true},"request_id":{"type":"string"},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable warning code (e.g. department_mismatch)."},"message":{"type":"string"},"detail":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false},"description":"Non-blocking signals emitted by this action (e.g., department_mismatch when source_job_id seeding produced a Department override). Omitted when empty."}},"required":["resource","action","execution_mode","approval","stage","data","validation","next_actions","web_url","request_id"],"additionalProperties":false,"description":"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."},"ModifyActiveResult":{"type":"object","properties":{"object":{"type":"string","enum":["interview_plan_modify_active_result"]},"action":{"type":"string","enum":["interview_plan.modify_active"]},"resource":{"type":"object","properties":{"type":{"type":"string","enum":["interview_plan"]},"id":{"type":"string","description":"Public `plan_…` id echoed from the request."}},"required":["type","id"],"additionalProperties":false},"mutated":{"type":"boolean","description":"Whether the bind actually wrote anything. False when every addressed content column already matched the active plan and the round diff was empty; the bind is still recorded, but no version was minted and no session moved."},"rounds":{"type":"array","items":{"type":"object","properties":{"round_id":{"type":"string"},"new_version_id":{"type":"string","nullable":true,"description":"Id of the newly minted active version for this round, or null for a removed round (removal deactivates versions and mints nothing)."},"old_version_id":{"type":"string","nullable":true,"description":"Id of the snapshot version locked sessions were pinned to, or null when no locked sessions existed."},"not_started_repointed":{"type":"integer","description":"Count of not_started sessions repointed to the new version."},"locked_pinned":{"type":"integer","description":"Count of in_progress/completed sessions pinned to the prior content."},"change_kind":{"type":"string","enum":["added","removed"],"description":"Present only on a round the edit added or removed; a changed round carries neither this key nor versions_deactivated."},"versions_deactivated":{"type":"integer","description":"Present only on a removed round: how many of its versions were deactivated."}},"required":["round_id","new_version_id","old_version_id","not_started_repointed","locked_pinned"],"additionalProperties":false},"description":"Per round the edit added, changed or removed: the versioning + reassignment outcome."},"sessions_repointed":{"type":"integer","description":"Total not_started sessions repointed across all changed rounds."},"locked_pinned":{"type":"integer","description":"Total locked sessions kept pinned across all changed rounds."},"affected_counts":{"type":"object","additionalProperties":{},"description":"Mode-scoped affected application and session counts."}},"required":["object","action","resource","mutated","rounds","sessions_repointed","locked_pinned","affected_counts"],"additionalProperties":false,"description":"Bind-path 200 for `interview_plan.modify_active`: the versioning + per-status session reassignment outcome. Returned only on the bind call; the preview (202) returns the shared approval-required envelope."},"InterviewPlan":{"type":"object","properties":{"object":{"type":"string","enum":["interview_plan"]},"id":{"type":"string"},"title":{"type":"string"},"role_name":{"type":"string"},"additional_info":{"type":"string","nullable":true},"outcomes":{},"competencies":{},"job_skills":{},"interview_sequence":{},"behavioral_anchors":{},"is_archived":{"type":"boolean"},"archived_at":{"type":"string","nullable":true},"archived_by":{"type":"string","nullable":true},"archived_reason":{"type":"string","nullable":true},"group_id":{"type":"string","nullable":true},"created_by":{"type":"string","nullable":true},"current_step":{"type":"integer","nullable":true},"visited_steps":{},"completed_steps":{},"version":{"type":"integer"},"location":{"type":"string","nullable":true},"location_type":{"type":"string","nullable":true},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","title","role_name","additional_info","is_archived","archived_at","archived_by","archived_reason","group_id","created_by","current_step","version","location","location_type","created_at","updated_at"],"additionalProperties":false},"InterviewPlanRead":{"type":"object","properties":{"object":{"type":"string","enum":["interview_plan"]},"id":{"type":"string"},"lifecycle":{"type":"string","enum":["published","draft"]},"title":{"type":"string"},"role_name":{"type":"string","nullable":true},"is_archived":{"type":"boolean"},"draft_status":{"type":"string","enum":["draft","validated","published","abandoned"],"nullable":true},"job_id":{"type":"string","nullable":true},"version":{"type":"integer","nullable":true},"rounds":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["interview_round"]},"round_id":{"type":"string"},"round_title":{"type":"string"},"description":{"type":"string","nullable":true},"duration":{"type":"number","nullable":true},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"scorecard_criteria":{"type":"array","items":{}},"questions":{"type":"array","items":{}},"interviewer_directions":{"type":"string","nullable":true},"candidate_directions":{"type":"string","nullable":true}},"required":["object","round_id","round_title","description","duration","kind","scorecard_criteria","questions","interviewer_directions","candidate_directions"],"additionalProperties":false}},"behavioral_anchors":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","lifecycle","title","role_name","is_archived","draft_status","job_id","version","rounds","behavioral_anchors","created_at","updated_at"],"additionalProperties":false},"InterviewPlanDraftRead":{"type":"object","properties":{"object":{"type":"string","enum":["interview_plan_draft"]},"id":{"type":"string"},"status":{"type":"string","enum":["draft","validated","published","abandoned"]},"job_id":{"type":"string","nullable":true},"role_context":{"type":"object","additionalProperties":{}},"outcomes":{"type":"array","items":{}},"competencies":{"type":"array","items":{}},"job_skills":{"type":"array","items":{}},"interview_sequence":{"type":"array","items":{}},"questions_and_directions":{"type":"object","additionalProperties":{}},"stage_versions":{"type":"object","additionalProperties":{}},"source_metadata":{"type":"object","additionalProperties":{}},"created_at":{"type":"string"},"updated_at":{"type":"string"}},"required":["object","id","status","job_id","role_context","outcomes","competencies","job_skills","interview_sequence","questions_and_directions","stage_versions","source_metadata","created_at","updated_at"],"additionalProperties":false,"description":"Full-content draft read: all stage checkpoints verbatim (questions carry derived `question_N` ids), the per-stage `stage_versions` map for `source_stage` preconditions, draft `status`, and `source_metadata` provenance."},"InterviewSession":{"type":"object","properties":{"object":{"type":"string","enum":["interview_session"]},"id":{"type":"string","description":"Display id, e.g. `is_<base32>`."},"application_id":{"type":"string","description":"Display id, e.g. `app_<base32>`."},"interview_plan_id":{"type":"string","nullable":true,"description":"Display id of the bound interview plan, e.g. `ipd_<base32>`."},"round":{"type":"object","properties":{"id":{"type":"string","description":"Stable interview-plan round id."},"title":{"type":"string","nullable":true,"description":"Trusted stored round title."}},"required":["id","title"],"additionalProperties":false},"status":{"type":"string","nullable":true},"booking_status":{"type":"string","nullable":true},"scheduled_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"scheduled_end_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"scheduled_timezone":{"type":"string","nullable":true,"description":"IANA timezone that preserves the scheduled wall-time intent, or null when the source did not provide an authoritative zone."},"started_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"completed_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"meeting_link":{"type":"string","nullable":true},"meeting_location":{"type":"string","nullable":true},"interview_version_id":{"type":"string","nullable":true,"description":"Display id of the assigned interview version, e.g. `iv_<base32>`."},"scorecard_criteria":{"type":"array","items":{}},"livemode":{"type":"boolean"},"created_at":{"type":"string","description":"ISO-8601 UTC"},"updated_at":{"type":"string","description":"ISO-8601 UTC"}},"required":["object","id","application_id","interview_plan_id","round","status","booking_status","scheduled_at","scheduled_end_at","scheduled_timezone","started_at","completed_at","meeting_link","meeting_location","interview_version_id","scorecard_criteria","livemode","created_at","updated_at"],"additionalProperties":false},"InterviewSessionList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"type":"object","properties":{"object":{"type":"string","enum":["interview_session"]},"id":{"type":"string","description":"Display id, e.g. `is_<base32>`."},"application_id":{"type":"string","description":"Display id, e.g. `app_<base32>`."},"interview_plan_id":{"type":"string","nullable":true,"description":"Display id of the bound interview plan, e.g. `ipd_<base32>`."},"round":{"type":"object","properties":{"id":{"type":"string","description":"Stable interview-plan round id."},"title":{"type":"string","nullable":true,"description":"Trusted stored round title."}},"required":["id","title"],"additionalProperties":false},"status":{"type":"string","nullable":true},"booking_status":{"type":"string","nullable":true},"scheduled_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"scheduled_end_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"scheduled_timezone":{"type":"string","nullable":true,"description":"IANA timezone that preserves the scheduled wall-time intent, or null when the source did not provide an authoritative zone."},"started_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"completed_at":{"type":"string","nullable":true,"description":"ISO-8601 UTC"},"meeting_link":{"type":"string","nullable":true},"meeting_location":{"type":"string","nullable":true},"interview_version_id":{"type":"string","nullable":true,"description":"Display id of the assigned interview version, e.g. `iv_<base32>`."},"scorecard_criteria":{"type":"array","items":{}},"livemode":{"type":"boolean"},"created_at":{"type":"string","description":"ISO-8601 UTC"},"updated_at":{"type":"string","description":"ISO-8601 UTC"}},"required":["object","id","application_id","interview_plan_id","round","status","booking_status","scheduled_at","scheduled_end_at","scheduled_timezone","started_at","completed_at","meeting_link","meeting_location","interview_version_id","scorecard_criteria","livemode","created_at","updated_at"],"additionalProperties":false}},"has_more":{"type":"boolean","enum":[false]}},"required":["object","data","has_more"],"additionalProperties":false},"AutomationRuleBulkResult":{"type":"object","properties":{"mode":{"type":"string","enum":["preview","apply"]},"action":{"type":"string","enum":["on","off","delete"]},"rules":{"type":"array","items":{"type":"object","properties":{"pipeline_template_id":{"type":"string","minLength":1,"nullable":true},"job_id":{"type":"string","minLength":1,"nullable":true},"needs_step_pick":{"type":"boolean"},"name":{"type":"string","maxLength":200},"starter_key":{"type":"string","maxLength":100,"nullable":true},"job_scope":{"type":"string","enum":["all_compatible","selected"]},"job_posting_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"]},"timing":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["immediate"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["delay"]},"delayMinutes":{"type":"integer","minimum":0}},"required":["type","delayMinutes"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["interview_relative"]},"anchor":{"type":"string","enum":["start","end"]},"offsetMinutes":{"type":"integer"}},"required":["type","anchor","offsetMinutes"],"additionalProperties":false}]},"pipeline_stage_id":{"type":"string","minLength":1,"nullable":true},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["create_task"]},"task_type":{"type":"string","minLength":1,"maxLength":200,"description":"Add to My Tasks: scorecard_review on feedback_submitted, or coordination for a general follow-up. Same-kind tasks are stacked."},"task_title":{"type":"string","minLength":1,"maxLength":500,"description":"Task title; {candidate} resolves to the candidate name."},"assigned_user_email":{"type":"string","minLength":1,"maxLength":320},"assigned_role":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner"]},"due_date":{"type":"string","minLength":1,"maxLength":64,"description":"Existing fixed deadline; use due_in for recurring rules."},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false,"description":"Due this many days or hours after the rule fires; at most 365 days or 8760 hours. Cannot combine with due_date."},"context":{"type":"object","additionalProperties":{}}},"required":["type","task_type","task_title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_email"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","interview_cancellation"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_scheduling_invitation"]},"interview_ids":{"type":"array","items":{"type":"string","minLength":1}},"format":{"type":"string","enum":["combined","separate"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type","interview_ids","format"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_preparation_email"]},"template_key":{"type":"string","enum":["candidate_preparation","onsite_logistics","technical_preparation"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_internal_email"]},"audience":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner","offer_approver","offer_requester"]},"template":{"type":"string","minLength":1,"maxLength":200}},"required":["type","audience","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["verify_calendar_event"]}},"required":["type"],"additionalProperties":false}]},"condition":{"type":"object","properties":{"step_position":{"anyOf":[{"type":"object","properties":{"which":{"type":"string","enum":["next"]}},"required":["which"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["first"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last_before"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"anchor_kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind","anchor_kind"],"additionalProperties":false}]},"public_application_only":{"type":"boolean"},"interview_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"step_kinds":{"type":"array","items":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"minItems":1}},"additionalProperties":true},"is_active":{"type":"boolean"},"position":{"type":"integer","minimum":0,"nullable":true},"id":{"type":"string"},"object":{"type":"string","enum":["automation_rule"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["pipeline_template_id","job_id","needs_step_pick","name","starter_key","job_scope","job_posting_ids","delivery_mode","timing","pipeline_stage_id","trigger","action","condition","is_active","position","id","object","created_at","updated_at"],"additionalProperties":false}},"skipped":{"type":"array","items":{"type":"object","properties":{"pipeline_template_id":{"type":"string","minLength":1,"nullable":true},"job_id":{"type":"string","minLength":1,"nullable":true},"needs_step_pick":{"type":"boolean"},"name":{"type":"string","maxLength":200},"starter_key":{"type":"string","maxLength":100,"nullable":true},"job_scope":{"type":"string","enum":["all_compatible","selected"]},"job_posting_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"]},"timing":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["immediate"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["delay"]},"delayMinutes":{"type":"integer","minimum":0}},"required":["type","delayMinutes"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["interview_relative"]},"anchor":{"type":"string","enum":["start","end"]},"offsetMinutes":{"type":"integer"}},"required":["type","anchor","offsetMinutes"],"additionalProperties":false}]},"pipeline_stage_id":{"type":"string","minLength":1,"nullable":true},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["create_task"]},"task_type":{"type":"string","minLength":1,"maxLength":200,"description":"Add to My Tasks: scorecard_review on feedback_submitted, or coordination for a general follow-up. Same-kind tasks are stacked."},"task_title":{"type":"string","minLength":1,"maxLength":500,"description":"Task title; {candidate} resolves to the candidate name."},"assigned_user_email":{"type":"string","minLength":1,"maxLength":320},"assigned_role":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner"]},"due_date":{"type":"string","minLength":1,"maxLength":64,"description":"Existing fixed deadline; use due_in for recurring rules."},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false,"description":"Due this many days or hours after the rule fires; at most 365 days or 8760 hours. Cannot combine with due_date."},"context":{"type":"object","additionalProperties":{}}},"required":["type","task_type","task_title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_email"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","interview_cancellation"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_scheduling_invitation"]},"interview_ids":{"type":"array","items":{"type":"string","minLength":1}},"format":{"type":"string","enum":["combined","separate"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type","interview_ids","format"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_preparation_email"]},"template_key":{"type":"string","enum":["candidate_preparation","onsite_logistics","technical_preparation"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_internal_email"]},"audience":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner","offer_approver","offer_requester"]},"template":{"type":"string","minLength":1,"maxLength":200}},"required":["type","audience","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["verify_calendar_event"]}},"required":["type"],"additionalProperties":false}]},"condition":{"type":"object","properties":{"step_position":{"anyOf":[{"type":"object","properties":{"which":{"type":"string","enum":["next"]}},"required":["which"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["first"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last_before"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"anchor_kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind","anchor_kind"],"additionalProperties":false}]},"public_application_only":{"type":"boolean"},"interview_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"step_kinds":{"type":"array","items":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"minItems":1}},"additionalProperties":true},"is_active":{"type":"boolean"},"position":{"type":"integer","minimum":0,"nullable":true},"id":{"type":"string"},"object":{"type":"string","enum":["automation_rule"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true},"reason":{"type":"string"}},"required":["pipeline_template_id","job_id","needs_step_pick","name","starter_key","job_scope","job_posting_ids","delivery_mode","timing","pipeline_stage_id","trigger","action","condition","is_active","position","id","object","created_at","updated_at","reason"],"additionalProperties":false}}},"required":["mode","action","rules","skipped"],"additionalProperties":false},"AutomationRule":{"type":"object","properties":{"pipeline_template_id":{"type":"string","minLength":1,"nullable":true},"job_id":{"type":"string","minLength":1,"nullable":true},"needs_step_pick":{"type":"boolean"},"name":{"type":"string","maxLength":200},"starter_key":{"type":"string","maxLength":100,"nullable":true},"job_scope":{"type":"string","enum":["all_compatible","selected"]},"job_posting_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"delivery_mode":{"type":"string","enum":["auto_send","auto_draft_review"]},"timing":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["immediate"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["delay"]},"delayMinutes":{"type":"integer","minimum":0}},"required":["type","delayMinutes"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["interview_relative"]},"anchor":{"type":"string","enum":["start","end"]},"offsetMinutes":{"type":"integer"}},"required":["type","anchor","offsetMinutes"],"additionalProperties":false}]},"pipeline_stage_id":{"type":"string","minLength":1,"nullable":true},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action":{"anyOf":[{"type":"object","properties":{"type":{"type":"string","enum":["create_task"]},"task_type":{"type":"string","minLength":1,"maxLength":200,"description":"Add to My Tasks: scorecard_review on feedback_submitted, or coordination for a general follow-up. Same-kind tasks are stacked."},"task_title":{"type":"string","minLength":1,"maxLength":500,"description":"Task title; {candidate} resolves to the candidate name."},"assigned_user_email":{"type":"string","minLength":1,"maxLength":320},"assigned_role":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner"]},"due_date":{"type":"string","minLength":1,"maxLength":64,"description":"Existing fixed deadline; use due_in for recurring rules."},"due_in":{"type":"object","properties":{"value":{"type":"integer","minimum":1,"maximum":8760},"unit":{"type":"string","enum":["days","hours"]}},"required":["value","unit"],"additionalProperties":false,"description":"Due this many days or hours after the rule fires; at most 365 days or 8760 hours. Cannot combine with due_date."},"context":{"type":"object","additionalProperties":{}}},"required":["type","task_type","task_title"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_email"]},"email_type":{"type":"string","enum":["acknowledgment","advancement","interview_confirmation","rejection","offer_declined","offer","hired","withdrawn","on_hold","interview_cancellation"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_scheduling_invitation"]},"interview_ids":{"type":"array","items":{"type":"string","minLength":1}},"format":{"type":"string","enum":["combined","separate"]},"template_key":{"type":"string","minLength":1,"maxLength":200}},"required":["type","interview_ids","format"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_preparation_email"]},"template_key":{"type":"string","enum":["candidate_preparation","onsite_logistics","technical_preparation"]}},"required":["type"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["send_internal_email"]},"audience":{"type":"string","enum":["assigned_interviewer","recruiter","hiring_manager","team_owner","offer_approver","offer_requester"]},"template":{"type":"string","minLength":1,"maxLength":200}},"required":["type","audience","template"],"additionalProperties":false},{"type":"object","properties":{"type":{"type":"string","enum":["verify_calendar_event"]}},"required":["type"],"additionalProperties":false}]},"condition":{"type":"object","properties":{"step_position":{"anyOf":[{"type":"object","properties":{"which":{"type":"string","enum":["next"]}},"required":["which"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["first"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind"],"additionalProperties":false},{"type":"object","properties":{"which":{"type":"string","enum":["last_before"]},"kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"anchor_kind":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]}},"required":["which","kind","anchor_kind"],"additionalProperties":false}]},"public_application_only":{"type":"boolean"},"interview_ids":{"type":"array","items":{"type":"string","minLength":1},"minItems":1},"step_kinds":{"type":"array","items":{"type":"string","enum":["candidate_interview","reference_check","internal_debrief","offer_meeting"]},"minItems":1}},"additionalProperties":true},"is_active":{"type":"boolean"},"position":{"type":"integer","minimum":0,"nullable":true},"id":{"type":"string"},"object":{"type":"string","enum":["automation_rule"]},"created_at":{"type":"string","nullable":true},"updated_at":{"type":"string","nullable":true}},"required":["pipeline_template_id","job_id","needs_step_pick","name","starter_key","job_scope","job_posting_ids","delivery_mode","timing","pipeline_stage_id","trigger","action","condition","is_active","position","id","object","created_at","updated_at"],"additionalProperties":false},"AutomationRun":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["automation_run"]},"rule_id":{"type":"string"},"application_id":{"type":"string"},"trigger":{"type":"string","enum":["stage_enter","stage_exit","step_ready","booking_created","booking_changed","step_completed","feedback_submitted","all_scorecards_submitted","interview_time","booking_cancelled","scorecard_due","scorecard_overdue","decision_brief_ready","coaching_report_ready","offer_approval_due","offer_approval_escalation_due"]},"action_type":{"type":"string"},"action_status":{"type":"string","enum":["executed","failed","skipped"]},"attempt_count":{"type":"integer"},"result_metadata":{"type":"object","additionalProperties":{},"nullable":true},"last_error":{"type":"string","nullable":true},"executed_at":{"type":"string","nullable":true},"public_state":{"type":"string","enum":["needs_review","scheduled","on_hold","in_progress","sent","completed","needs_attention","skipped","cancelled"]},"reason":{"type":"string","nullable":true},"next_action":{"type":"string","nullable":true},"due_at":{"type":"string","nullable":true},"interview_session_id":{"type":"string","nullable":true}},"required":["id","object","rule_id","application_id","trigger","action_type","action_status","attempt_count","result_metadata","last_error","executed_at","public_state","reason","next_action","due_at","interview_session_id"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"type":{"type":"string","enum":["invalid_request_error","authentication_error","permission_error","rate_limit_error","api_error"]},"code":{"type":"string"},"message":{"type":"string"},"param":{"type":"string"},"request_id":{"type":"string"}},"required":["type","code","message","request_id"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Canonical API error envelope. Every 404 not-found response uses a resource-specific code and includes param with the exact body field or path parameter that referenced the unavailable resource. Use code and param for programmatic handling, and request_id for support; message text is not a stable contract."},"ListEnvelope":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{}},"has_more":{"type":"boolean"}},"required":["object","data","has_more"],"additionalProperties":false,"description":"Cursor-paginated list envelope."},"AutomationRuleOverlap":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","blocking_rule"],"properties":{"type":{"type":"string","enum":["invalid_request_error"]},"code":{"type":"string","enum":["automation_rule_overlap"]},"message":{"type":"string"},"request_id":{"type":"string"},"blocking_rule":{"type":"object","required":["id","name","url"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string","example":"/jobs/<job_id>?tab=automations&rule=<rule_id>"}}}}}}}}}}