Cancel a scheduled interview session

Cancel a scheduled interview session

Required scopes: scheduling:write

Cancels 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.

Example (curl):

curl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/cancel \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c3a…' \
  -d '{"reason":"Hiring manager unavailable"}'

Example (TypeScript):

await fetch(
  "https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/cancel",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.YS_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify({ reason: "Hiring manager unavailable" }),
  },
).then((r) => r.json());