---
title: "Generate a scheduling link for an interview session"
method: POST
path: "/v1/interview_sessions/{interview_session_id}/actions/generate_link"
tags: ["Scheduling"]
---

# Generate a scheduling link for an interview session

`POST /v1/interview_sessions/{interview_session_id}/actions/generate_link`

## Request

- Base URL: `https://api.yardstick.team`
- URL: `https://api.yardstick.team/v1/interview_sessions/{interview_session_id}/actions/generate_link`
- Auth: HTTP bearer

Generate a scheduling link for an interview session

**Required scopes:** `scheduling:write`

Mints 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`.

**Example (curl):**

```bash
curl -X POST https://api.yardstick.team/v1/interview_sessions/is_abc123/actions/generate_link \
  -H 'Authorization: Bearer ys_sk_live_…' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7c3a…' \
  -d '{}'
```

**Example (TypeScript):**

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

## Path parameters

- `interview_session_id` string, required

## Headers

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

## Response `200`

Link minted. Each call generates a fresh scheduling link; previous links remain valid until their TTL expires.

- SchedulingGenerateLinkResponse: Provider-agnostic success envelope for `scheduling.generate_link`. Each call mints a fresh link; previous links remain valid until their TTL expires.
  - `scheduling_link` string, required: Provider-rendered scheduling URL. Treat as opaque; do not parse.
  - `provider` 'calcom' | 'calendly', required: Underlying provider that minted the link.
  - `expires_at` string, required: ISO-8601 UTC timestamp at which the corresponding `scheduling_link_tokens` row expires (30-day TTL).
  - `link_id` string, required: Display id of the `scheduling_link_tokens` row backing this link. Use for out-of-band revocation lookups.

## Other responses

- `400`: Invalid request
- `401`: Authentication failure
- `403`: Permission denied (scope or feature flag)
- `404`: Resource not found. The error uses the resource-specific code and param names the exact body field or path parameter that referenced it.
- `409`: Blocked by a structured scheduling blocker. Body carries `blocker_code`, `blocker_message`, and `blocker_metadata`.
- `429`: Rate limited
- `500`: Internal error

---

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