Onboarding

Clients get the project's currently-active onboarding flow via GET /client/onboarding; state transitions use the lifecycle endpoints. user_onboarding rows are upserted on (app_user_id, flow_id).

Source: apps/api/src/routes/client/onboarding.ts.

Endpoints

Method	Path	Description
GET	`/client/onboarding`	Current flow + user progress.
POST	`/client/onboarding/:flowId/start`	Start or restart a flow.
POST	`/client/onboarding/:flowId/advance`	Advance to the next step.
POST	`/client/onboarding/:flowId/skip`	Mark the flow skipped.
POST	`/client/onboarding/:flowId/complete`	Mark the flow completed.

GET /client/onboarding

Returns the newest active flow plus the caller's progress, or data: null if no active flow exists.

Response 200

{
  "data": {
    "flow": { "id": "…", "name": "…", "steps": [{ "id": "welcome" }], "is_active": true },
    "progress": {
      "app_user_id": "…",
      "flow_id": "…",
      "current_step": "welcome",
      "completed_steps": [],
      "status": "in_progress"
    }
  }
}

Errors

500 FETCH_FAILED.

Try it:

GET/client/onboarding

client auth

curl -X GET 'https://api.amba.dev/client/onboarding'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET '${BASE_URL}/client/onboarding' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}'

POST /client/onboarding/:flowId/start

Upserts the user_onboarding row, setting current_step to the flow's first step id and status = 'in_progress'.

Response 201

Updated / inserted row.

Errors

500 CREATE_FAILED.

Try it:

POST/client/onboarding/%7B%7BflowId%7D%7D/start

client auth

curl -X POST 'https://api.amba.dev/client/onboarding/%7B%7BflowId%7D%7D/start'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/onboarding/{flowId}/start' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/onboarding/:flowId/advance

Appends the current step to completed_steps and moves to the next step. If there's no next step, status = 'completed' and completed_at = NOW().

Response 200

Updated row.

Errors

404 NOT_FOUND — the user has no user_onboarding row for this flow (call /start first).
500 UPDATE_FAILED.

Try it:

POST/client/onboarding/%7B%7BflowId%7D%7D/advance

client auth

curl -X POST 'https://api.amba.dev/client/onboarding/%7B%7BflowId%7D%7D/advance'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/onboarding/{flowId}/advance' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/onboarding/:flowId/skip

Sets status = 'skipped' and completed_at = NOW().

Errors

404 UPDATE_FAILED — onboarding not started.

Try it:

POST/client/onboarding/%7B%7BflowId%7D%7D/skip

client auth

curl -X POST 'https://api.amba.dev/client/onboarding/%7B%7BflowId%7D%7D/skip'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/onboarding/{flowId}/skip' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

POST /client/onboarding/:flowId/complete

Sets status = 'completed' and completed_at = NOW().

Errors

404 UPDATE_FAILED.

Try it:

POST/client/onboarding/%7B%7BflowId%7D%7D/complete

client auth

curl -X POST 'https://api.amba.dev/client/onboarding/%7B%7BflowId%7D%7D/complete'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST '${BASE_URL}/client/onboarding/{flowId}/complete' \
  -H 'X-Api-Key: ${CLIENT_API_KEY}' \
  -H 'Authorization: Bearer ${SESSION_TOKEN}' \
  -H 'Content-Type: application/json' \
  -d '{}'

On this page