REST API

Choose the API for app delivery or backend workspace operations.

Use Nuxie’s APIs to record customer activity, check access, and connect your backend to your Experiences. The API and key you need depend on where the request comes from.

Choose an API

The SDKs use the App API and handle identity, offline delivery, and retries for you. Start with an SDK when integrating a mobile app or game. Use the Workspace API for server-side work.

Choose an operation below for request fields, response fields, and complete examples. App API publishable keys cannot authenticate Workspace API requests.

Base URL

App API requests use:

https://i.nuxie.ai

The publishable key selects the App and its test or live environment.

Authentication and environments

POST requests include the app’s publishable key in the JSON body as apiKey. GET /status and GET /event accept it as the apiKey query parameter.

• Test keys start with pk_test_.
• Live keys start with pk_live_.

Copy the keys from Connect your app. Use a test key in development builds and a live key in release builds. These keys allow app requests; they do not grant dashboard administration access.

Send a request

Send JSON with Content-Type: application/json. For example, check whether a customer has access to premium-export:

curl https://i.nuxie.ai/entitled \
  --header 'Content-Type: application/json' \
  --data '{
    "apiKey": "pk_test_example",
    "customerId": "user-456",
    "featureId": "premium-export"
  }'

Replace the example key, customer ID, and Feature key with values from your App. A publishable key belongs to a platform within the App; use the key for the platform making the request.

Customer identifiers

Use the same customer ID across event, access, and purchase requests. The event and purchase endpoints call this field distinct_id; Feature endpoints use customerId. Both refer to the ID your app supplies, such as user-456, rather than Nuxie’s internal customer record ID.

For signed-out customers, use the SDK’s anonymous ID. Customer IDs must be non-empty and no longer than 256 characters. Placeholder values such as anonymous, guest, undefined, and null are rejected.

Use SDK identity methods to connect anonymous activity to a signed-in customer and reset identity on sign-out.

Endpoint summary

POST /profile

Fetch Feature access and signed Experience releases. The endpoint supports ETags so an unchanged profile can return 304.

Get a customer profile →

POST /event

Record customer activity or update customer properties. Reuse the event UUID for retries.

Record an event →

POST /batch

Send 1–1,000 events as gzip-compressed JSON. Inspect each item’s acceptance result before retrying.

Record a batch of events →

POST /entitled

Check whether a customer has access or enough units for an action. This request does not spend units.

Check Feature access →

POST /feature/consume

Spend units using a stable operation ID. Start the paid work only after the response says accepted: true.

Consume Feature usage →

POST /purchase

Verify an App Store or Google Play purchase and attach its Feature access to a customer.

Synchronize a purchase →

POST /app-store/intro-eligibility

Get a signed App Store introductory-offer decision for a purchase placement. The SDK supplies its Journey context.

Resolve introductory eligibility →

GET /status

Check the app configuration associated with a publishable key.

Check app status →

GET /health

Check the App API service without authentication.

Check service health →

GET /event

Check a publishable key without recording an event.

Test event authentication →

Errors and retries

Error responses include a message or structured validation issues. Common status codes include:

Retry a transient 429 or 503 with backoff and the original event UUID, operation ID, or purchase evidence. For a 400, inspect and correct the request before retrying. Check structured response fields as well as HTTP status: a successful access check can deny access, and a usage response can reject an operation.

Keep the same identifier when retrying. A new operation ID represents a new usage request and can spend units again.

When requesting help, include the endpoint, HTTP status, response code, and X-Request-Id when present. Remove customer data and purchase evidence from shared logs.

Workspace API

Workspace requests use https://api.nuxie.ai/v1. You can read or manage apps, projects, customers, and Products, query event data, and start API-triggered Experiences. See the API explorer for resource schemas.

Workspace authentication

Send a secret workspace key beginning with sk_ in Authorization: Bearer <key>. Keep this key on your server. The pk_test_ and pk_live_ keys from Connect your app are for the App API.

Set X-Nuxie-Env: test while developing and X-Nuxie-Env: live for production. Workspace requests default to live if you omit the header; the key’s name or prefix does not select the environment.

To create a key, use an account with an email/password login and a verified email address:

1. Create a user session with your email and password.
2. List your workspaces using the returned user session bearer token.
3. Create a workspace API key for a workspace where you are an owner or admin.

Save the secret when it is created; later key listings do not return it. The user session token manages keys, while the resulting workspace key authenticates your backend’s workspace requests.

Workspace API access also depends on your plan and billing status. A 401 means the key is missing, invalid, expired, or the wrong kind. A 402 with api_access_required or billing_payment_required means the workspace needs API access or an outstanding payment resolved. These codes differ from App API usage decisions above.

Start an Experience

Use an API call when a backend event should start an Experience for a customer. Publish the Experience with an API call trigger, then call it with the app platform ID, the customer’s SDK identity, and any event context.

Start an Experience →

Next steps

• SDK guides
• System Events
• Webhooks