---
title: "Start Setup From Picker"
method: POST
path: "/v1/onboarding/setup-from-picker"
tags: ["onboarding"]
---

# Start Setup From Picker

`POST /v1/onboarding/setup-from-picker`

Skip-discovery entry point. The questionnaire path on /onboarding (and,
later, the dashboard "Create new template" CTA) calls this to start a setup
interview directly without going through a discovery call first.

Builds the same `interview.context.prefill` shape that the discovery-handoff
webhook writes, so the specialist agent's PREFILL AWARENESS / recap behavior
works identically regardless of entry path.

If `surface == "embedded"`, attaches the "Embed Setup Handoff" skill at
session-creation time. Other surfaces don't get the skill — they'll never
hear MCP / API-key / coding-agent talk during setup.

## Request body

- PickerSetupRequest — Body for /v1/onboarding/setup-from-picker. Mirrors the prefill shape that the discovery-handoff webhook writes, but sourced from the questionnaire instead of from a discovery transcript. The specialist setup template runs against either source identically; its PREFILL AWARENESS prefix collapses empty fields gracefully.
  - `kind` string, required
  - `surface` string, nullable
  - `language` string, nullable
  - `picker_answers` PickerQuestionnaireEntry[], nullable
    - `question` string, required
    - `answer` string, required
  - `free_text` string, nullable
  - `picker_leaf` string, nullable

## Response `200`

Successful Response

- OnboardingSessionOut
  - `session_id` string, required
  - `interview_id` string, required
  - `join_token` string, required
  - `room_name` string, required
  - `livekit_url` string, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.dev/roxels/apis/interviewer.md) · [All operations](https://skmtc.dev/roxels/apis/interviewer/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/roxels/interviewer/revisions/4ef48ed226e1/schema)