Start an Experience

Start an API-triggered Experience from your backend.

POSThttps://api.nuxie.ai/v1/experiences/{experienceId}/start

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 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

experienceIdpathstringrequired

ID of the published Experience.

X-Nuxie-Envheaderstring

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

Idempotency-Keyheaderstring

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_idbodystringrequired

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

distinct_idbodystringrequired

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

contextbodyobject

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.

objectstringrequired

experience_start.

experience_idstringrequired

Requested Experience ID.

journey_idstringrequired

Journey ID, or null when the customer is ineligible.

statusstringrequired

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 for choosing between API calls, app events, and schedules.

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"
  }
}'

{
  "object": "experience_start",
  "experience_id": "experience-id",
  "journey_id": "journey-id",
  "status": "started"
}