---
title: "POST /v1/users/me/onboarding-state/transitions"
method: POST
path: "/v1/users/me/onboarding-state/transitions"
tags: ["Users"]
---

# POST /v1/users/me/onboarding-state/transitions

`POST /v1/users/me/onboarding-state/transitions`

Applies one transition to the authenticated user's onboarding state and returns the resulting state. Each transition is persisted before the response is sent, so the stored state always reflects the last transition that applied. Transitions: `record-entry-path`, `complete-setup`, `choose-flow`, `advance`, `complete`, `skip-onboarding`.

## Headers

- `Authorization` string

## Request body

- union
  - object
    - `type` 'record-entry-path', required
    - `path` union, required
      - 'cli'
      - 'web'
  - object
    - `type` 'choose-flow', required
    - `flowSlug` union, required
      - 'review-skill'
      - 'review-code'
    - `chosenVia` union, required
      - 'picker'
      - 'deep-link'
      - 'default'
    - `toBeatOrder` integer
    - `skippedBeatOrders` integer[]
    - `path` union
      - 'cli'
      - 'web'
  - object
    - `type` 'advance', required
    - `toBeatOrder` integer, required
    - `skippedBeatOrders` integer[]
  - object
    - `type` 'complete', required
    - `skippedBeatOrders` integer[]
  - object
    - `type` 'skip-onboarding', required
  - object
    - `type` 'complete-setup', required

## Response `200`

Default Response

- object
  - `links` object, required
    - `self` string, uri, required
  - `data` object, required
    - `id` string, uuid, required
    - `type` 'onboarding-state', required
    - `attributes` object, required
      - `onboardingCompleted` boolean, required
      - `onboardingCompletedAt` string, date-time, nullable, required
      - `cliLastSeenAt` string, date-time, nullable, required
      - `cliLastVersion` string, nullable, required
      - `state` object, nullable, required
        - `flowSlug` string, nullable, required
        - `path` union, required
          - 'cli'
          - 'web'
        - `chosenVia` union, required
          - 'picker'
          - 'deep-link'
          - 'default'
        - `currentBeatOrder` integer, required
        - `skippedBeatOrders` integer[], required
        - `startedAt` string, date-time, required
        - `lastActivityAt` string, date-time, required
        - `setupSubmittedAt` string, date-time, nullable, required
        - `completedAt` string, date-time, nullable, required
      - `facts` object, required

## Other responses

- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `500` — Internal Server Error

## Changes

- **2026-09-15** `d50a02b79ad3` — 2 info
  - added the optional property `error/code` to the response with the `403` status
  - added the optional property `error/url` to the response with the `403` status
- **2026-09-03** `538ff8b269b7` — 2 info
  - added `subschema #6` to the request body `anyOf` list
  - added the required property `data/attributes/state/anyOf[subschema #1]/setupSubmittedAt` to the response with the `200` status
- **2026-09-02** `d18817d8161c` — 1 info
  - added the required property `data/attributes/cliLastVersion` to the response with the `200` status
- **2026-08-27** `64ef6ca73e52` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/tessl/apis/tessl-api/changes/v1/users/me/onboarding-state/transitions/post.md)

---

[API](https://skmtc.dev/tessl/apis/tessl-api.md) · [All operations](https://skmtc.dev/tessl/apis/tessl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tessl/apis/tessl-api/revisions/6941f1403761?raw)