---
title: "Start an Experience"
description: "Start an API-triggered Experience from your backend."
api: POST https://api.nuxie.ai/v1/experiences/{experienceId}/start
authMethod: bearer
playground: simple
search:
  tags: ["api", "workspace", "reference"]
  keywords: ["API call", "Idempotency-Key", "app_id", "distinct_id", "X-Nuxie-Env", "Journey"]
---

Start an Experience when something happens on your backend, such as a training plan becoming ready. Publish the Experience with an **API call** trigger for the app platform and environment you will use.

## Authentication

Send a secret workspace `sk_` key as `Authorization: Bearer <key>`. [Create a workspace API key](/docs/api-reference/workspace/create-api-key) if you do not have one. Keep this key on your server; the app's publishable `pk_test_` and `pk_live_` keys cannot authenticate this request.

## Request

- **`experienceId`** · path · `string` · required

  ID of the published Experience.

- **`X-Nuxie-Env`** · header · `string`

  `test` or `live`. Defaults to `live` when omitted; the workspace key does not select the environment.

- **`Idempotency-Key`** · header · `string`

  Identifier for this occurrence. Reuse it when retrying the same request for the same customer, app, and Experience. If omitted, each request gets a new key.

- **`app_id`** · body · `string` · required

  App platform ID returned as `id` by `GET /v1/apps`, rather than the parent App or workspace ID.

- **`distinct_id`** · body · `string` · required

  The same identified or anonymous customer ID your app supplies to the SDK. Nuxie resolves or creates the customer for this request.

- **`context`** · body · `object`

  Values made available to the Journey as event data, such as `{"plan_id":"plan-123"}`.

## Response

A valid request returns `202`. Read `status` to find out whether a Journey started.

- **`object`** · `string` · required

  `experience_start`.

- **`experience_id`** · `string` · required

  Requested Experience ID.

- **`journey_id`** · `string` · required

  Journey ID, or `null` when the customer is ineligible.

- **`status`** · `string` · required

  `started`, `coalesced`, or `ineligible`.

- `started`: a Journey began.
- `coalesced`: Nuxie combined this request with an earlier Journey instead of starting another run.
- `ineligible`: no Journey started.

A successful response does not mean a screen has appeared on the device. Delivery still follows the Journey and its conditions.

## Retries and errors

Keep the same `Idempotency-Key` when retrying an accepted start. It prevents that occurrence from creating a second Journey. Use a new key for a new occurrence.

A `401` means the key is missing, invalid, expired, or the wrong kind. Workspace API access depends on your plan and billing status: `402` with `api_access_required` or `billing_payment_required` means API access or an outstanding payment needs attention. A temporary service failure can return `503`.

See [Delivery](/docs/guides/delivery#api-calls) for choosing between API calls, app events, and schedules.

```sh title="cURL"
curl https://api.nuxie.ai/v1/experiences/experience-id/start \
  --header "Authorization: Bearer $NUXIE_WORKSPACE_API_KEY" \
  --header 'X-Nuxie-Env: test' \
  --header 'Idempotency-Key: training-plan-ready-123' \
  --header 'Content-Type: application/json' \
  --data '{
  "app_id": "app-platform-id",
  "distinct_id": "user-456",
  "context": {
    "plan_id": "plan-123"
  }
}'
```

```json title="202"
{
  "object": "experience_start",
  "experience_id": "experience-id",
  "journey_id": "journey-id",
  "status": "started"
}
```