---
title: "Apply a first-run onboarding state transition"
method: PUT
path: "/api/onboarding"
tags: ["Onboarding"]
---

# Apply a first-run onboarding state transition

`PUT /api/onboarding`

## Request body

- union
  - object
    - `action` 'view', required
    - `step` 'connect' | 'name' | 'ai' | 'agents' | 'memory' | 'integrations' | 'first_task', required
  - object
    - `action` 'complete', required
    - `step` 'connect', required
    - `method` 'api_key', required
  - object
    - `action` 'complete', required
    - `step` 'name', required
    - `method` 'custom_name' | 'default_name', required
  - object
    - `action` 'complete', required
    - `step` 'ai', required
    - `method` 'claude_setup_token' | 'claude_api_key' | 'codex_device' | 'codex_cli' | 'openrouter' | 'openai_gateway' | 'deepseek' | 'devin', required
  - object
    - `action` 'complete', required
    - `step` 'agents', required
    - `method` 'cheap' | 'optimal' | 'max' | 'mixed', required
  - object
    - `action` 'complete', required
    - `step` 'integrations', required
    - `method` 'slack' | 'github' | 'gitlab' | 'linear_oauth' | 'jira_oauth', required
  - object
    - `action` 'skip', required
    - `step` 'name' | 'ai' | 'agents' | 'memory' | 'integrations' | 'first_task', required
  - object
    - `action` 'fail', required
    - `step` 'connect' | 'name' | 'ai' | 'agents' | 'memory' | 'integrations' | 'first_task', required
    - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown', required
  - object
    - `action` 'first_task', required
    - `taskId` string, required
    - `method` 'suggestion' | 'free_form', required
  - object
    - `action` 'minimize', required
  - object
    - `action` 'resume', required
  - object
    - `action` 'dismiss', required

## Response `200`

Updated onboarding state and signals

- object
  - `state` object, required
    - `version` 1, required
    - `startedAt` string, date-time, required
    - `currentStep` 'connect' | 'name' | 'ai' | 'agents' | 'memory' | 'integrations' | 'first_task', required
    - `minimizedAt` string, date-time, nullable, required
    - `dismissedAt` string, date-time, nullable, required
    - `completedAt` string, date-time, nullable, required
    - `autoCompleted` boolean, required
    - `firstTaskId` string, nullable, required
    - `steps` object, required
      - `connect` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'api_key' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `name` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'custom_name' | 'default_name' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `ai` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'claude_setup_token' | 'claude_api_key' | 'codex_device' | 'codex_cli' | 'openrouter' | 'openai_gateway' | 'deepseek' | 'devin' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `agents` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'cheap' | 'optimal' | 'max' | 'mixed' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `memory` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'openai' | 'openrouter' | 'vercel' | 'custom' | 'existing' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `integrations` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'slack' | 'github' | 'gitlab' | 'linear_oauth' | 'jira_oauth' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
      - `first_task` object, required
        - `status` 'todo' | 'done' | 'skipped' | 'failed', required
        - `at` string, date-time, nullable, required
        - `method` 'suggestion' | 'free_form' | 'null', nullable, required
        - `errorClass` 'auth' | 'network' | 'timeout' | 'dimension' | 'model' | 'not_enabled' | 'expired' | 'unknown' | 'null', nullable, required
  - `signals` object, required
    - `providers` object[], required
      - `provider` 'claude' | 'codex' | 'pi' | 'devin' | 'claude-managed' | 'opencode' | 'acp' | 'dsh', required
      - `state` 'unverified' | 'configured' | 'verified', required
      - `workers` integer, required
      - `verifiedWorkers` integer, required
    - `embeddings` object, required
      - `configured` boolean, required
      - `dimensions` integer, required
    - `integrations` object, required
      - `slack` boolean, required
      - `github` boolean, required
      - `gitlab` boolean, required
      - `linear` boolean, required
      - `jira` boolean, required
    - `agents` object, required
      - `leadsOnline` integer, required
      - `workersOnline` integer, required
    - `firstTask` object, nullable, required
      - `id` string, required
      - `status` string, required

## Other responses

- `400` — Invalid transition
- `404` — First task not found

## Changes

- **2026-09-25** `452be3d6b59a` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/changes/api/onboarding/put.md)

---

[API](https://skmtc.dev/desplega-ai/apis/agent-swarm-api.md) · [All operations](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/llms.txt) · [OpenAPI document](https://skmtc.dev/desplega-ai/apis/agent-swarm-api/revisions/01e2386c97da?raw)