---
title: "REST API"
description: "Choose the API for app delivery or backend workspace operations."
search:
  tags: ["api", "reference"]
  keywords: ["REST", "HTTP", "publishable key", "workspace API key"]
---

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

| You want to… | API | Authentication |
| --- | --- | --- |
| Send app events, check Feature access, consume usage, or report purchases | **App API**, `https://i.nuxie.ai` | Publishable app key, usually in the JSON body as `apiKey` |
| Manage workspace resources or start an Experience from your backend | **[Workspace API](#workspace-api)**, `https://api.nuxie.ai/v1` | Secret workspace key in `Authorization: Bearer …` |

The [SDKs](/docs/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:

```text
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`:

```sh
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](/docs/reference) to connect anonymous activity to a signed-in customer and reset identity on sign-out.

## Endpoint summary

| Method | Path | Purpose |
|---|---|---|
| `POST` | [`/profile`](/docs/api-reference/app/profile) | Fetch customer state and signed Experience releases |
| `POST` | [`/event`](/docs/api-reference/app/event) | Record one event |
| `POST` | [`/batch`](/docs/api-reference/app/batch) | Deliver 1–1,000 gzip-compressed events |
| `POST` | [`/entitled`](/docs/api-reference/app/entitled) | Read a customer’s access to a Feature |
| `POST` | [`/feature/consume`](/docs/api-reference/app/consume) | Record Feature usage with a retry-safe operation ID |
| `POST` | [`/purchase`](/docs/api-reference/app/purchase) | Synchronize an App Store or Google Play purchase |
| `POST` | [`/app-store/intro-eligibility`](/docs/api-reference/app/intro-eligibility) | Resolve App Store introductory-offer eligibility |
| `GET` | [`/status`](/docs/api-reference/app/status) | Verify app configuration is available at the edge |
| `GET` | [`/health`](/docs/api-reference/app/health) | Check service health |
| `GET` | [`/event`](/docs/api-reference/app/test-authentication) | Test event authentication without recording activity |

## POST /profile

<span id="feature-state" />
<span id="response-headers" />

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

[Get a customer profile →](/docs/api-reference/app/profile)

## POST /event

<span id="customer-properties" />
<span id="response" />

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

[Record an event →](/docs/api-reference/app/event)

## POST /batch

<span id="response-1" />

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

[Record a batch of events →](/docs/api-reference/app/batch)

## POST /entitled

<span id="response-2" />

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

[Check Feature access →](/docs/api-reference/app/entitled)

## POST /feature/consume

<span id="response-3" />
<span id="purchase-and-first-use" />

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

[Consume Feature usage →](/docs/api-reference/app/consume)

## POST /purchase

<span id="app-store-request" />
<span id="google-play-request" />
<span id="response-4" />
<span id="purchase-errors" />

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

[Synchronize a purchase →](/docs/api-reference/app/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 →](/docs/api-reference/app/intro-eligibility)

## GET /status

Check the app configuration associated with a publishable key.

[Check app status →](/docs/api-reference/app/status)

## GET /health

Check the App API service without authentication.

[Check service health →](/docs/api-reference/app/health)

## GET /event

Check a publishable key without recording an event.

[Test event authentication →](/docs/api-reference/app/test-authentication)

## Errors and retries

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

| Status | Meaning |
|---|---|
| `400` | Invalid body, identity, or command |
| `401` | Missing, invalid, or revoked key |
| `402` | A usage or purchase-backed usage command has insufficient balance |
| `403` | Request scope does not match the authenticated App or environment |
| `404` | Journey or resource not found |
| `409` | Identity, Journey, or operation-ID conflict |
| `410` | Customer was deleted |
| `413` | Request payload is too large |
| `429` | Purchase verification is temporarily rate-limited |
| `500` | The request could not be completed because of a server error |
| `503` | Required edge configuration or downstream authority unavailable |

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](https://api.nuxie.ai/docs) 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](/docs/api-reference/workspace/create-session) with your email and password.
2. [List your workspaces](/docs/api-reference/workspace/list-workspaces) using the returned user session bearer token.
3. [Create a workspace API key](/docs/api-reference/workspace/create-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 →](/docs/api-reference/workspace/start-experience)

## Next steps

- [SDK guides](/docs/sdks)
- [System Events](/docs/api-reference/system-events)
- [Webhooks](/docs/api-reference/webhooks)