> For the complete documentation index, see [llms.txt](https://docs.visualsentinel.com/llms.txt)

# Onboarding API

User onboarding flow. This page lists all 4 endpoints in the Onboarding area of the Visual Sentinel REST API.

Base URL: `https://visualsentinel.com`. Unless an endpoint says otherwise it accepts an API key or a session cookie, see [Authentication](https://docs.visualsentinel.com/guides/authentication.md). Most error responses use the [ErrorResponse](https://docs.visualsentinel.com/reference/models/error-response.md) shape, see [Errors](https://docs.visualsentinel.com/guides/errors.md) and [Rate limits](https://docs.visualsentinel.com/guides/rate-limits.md).

## Endpoints

- [Get onboarding status](#get-onboarding-status): `GET /api/onboarding/status`
- [Select plan during onboarding](#select-onboarding-plan): `POST /api/onboarding/select-plan`
- [Auto-setup during onboarding](#auto-setup): `POST /api/onboarding/auto-setup`
- [Start no-card trial](#start-no-card-trial): `POST /api/onboarding/start-no-card-trial`

## Get onboarding status

`GET /api/onboarding/status`

Get the user's onboarding progress.

**Responses**

- `200`: Onboarding status.

## Select plan during onboarding

`POST /api/onboarding/select-plan`

Select a plan as part of the onboarding flow.

**Responses**

- `200`: Plan selected.

## Auto-setup during onboarding

`POST /api/onboarding/auto-setup`

Automatically create a monitor from a URL during onboarding.

**Responses**

- `200`: Auto-setup complete.

## Start no-card trial

`POST /api/onboarding/start-no-card-trial`

When trials without a card are available, starts a 10-day trial of a paid plan with no card, for the owner of an eligible workspace who signed up with a work email and has a verified address. Signed-in sessions only; API keys and support sessions are refused. Otherwise it answers with a code that says why (for example BUSINESS_EMAIL_REQUIRED, TRIAL_ALREADY_USED or NO_CARD_TRIAL_UNAVAILABLE); where the workspace can still have a trial with a card, start it from checkout instead (POST /api/billing/checkout). A request for a trial that is already running answers 200 with idempotent true and changes nothing.

Codes: NO_CARD_TRIAL_UNAVAILABLE (403), OWNER_REQUIRED (403), BUSINESS_EMAIL_REQUIRED (403), EMAIL_VERIFICATION_REQUIRED (403), TRIAL_ALREADY_USED (409), TRIAL_DOMAIN_USED (409).

Authentication: session cookie only. API keys are refused.

Request body (required): object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `plan` | string | Yes | The plan to try, at its normal limits (legacy names 'enterprise' and 'professional' are accepted; 'free' is refused). One of: `solo`, `starter`, `business`, `agency`. |
| `triggerSource` | string | Yes | Where the request came from. The plan step sends onboarding_select_plan. One of: `monitor_cap_hit`, `feature_gate_clicked`, `first_monitor_onboarding`, `lifecycle_email_cta`, `admin_grant`, `dashboard_cta`, `billing_cta`, `onboarding_select_plan`, `paid_decision_card`. |

**Responses**

- `200`: Trial started, or already running (idempotent true) Body: object.
- `400`: Invalid body: plan must be solo, starter, business or agency, and triggerSource is required.
- `401`: Not signed in.
- `403`: An API key (code SESSION_REQUIRED), a support session (code NOT_DURING_SUPPORT_SESSION), a missing or invalid CSRF token, or a refusal: NO_CARD_TRIAL_UNAVAILABLE (this workspace cannot have a trial without a card), OWNER_REQUIRED (only the workspace owner can start it), BUSINESS_EMAIL_REQUIRED (not available for this email address; where the workspace can still have a trial, a trial with a card starts from checkout), EMAIL_VERIFICATION_REQUIRED (verify the email address first) Body: object.
- `404`: Organization not found.
- `409`: A refusal: TRIAL_ALREADY_USED (this account or workspace already had a trial or a subscription) or TRIAL_DOMAIN_USED (the company already had a trial or a plan) Body: object.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `success` | boolean | No |   |
| `idempotent` | boolean | No | True when the trial was already running; nothing changed. |
| `plan` | string | No | The trial's plan: SOLO, STARTER, BUSINESS or AGENCY. |
| `trialEndsAt` | string (date-time) | No |   |
| `message` | string | No |   |

Generated from the OpenAPI 3.1 specification at [https://docs.visualsentinel.com/openapi.json](https://docs.visualsentinel.com/openapi.json), the same file the interactive reference reads.