REST API

Edge API endpoints for events, profiles, entitlements, and purchases

REST API

The Nuxie edge API handles all SDK communication. These endpoints process events, deliver profiles, check entitlements, and sync purchases.

Base URL

All endpoints are served from your Nuxie ingest URL:

https://ingest.nuxie.io

Authentication

Every request must include your API key. For POST endpoints, include the key in the request body. For GET endpoints, include it as a query parameter.

{
  "apiKey": "nux_live_abc123..."
}

API keys are scoped to a single app and environment (test or live). Generate keys in the dashboard under Settings > API Keys.

Warning: Never expose live API keys in client-side code that is not compiled into a native app. The iOS SDK handles key management automatically.

POST /event

Submit a single event.

Request body

{
  "apiKey": "nux_live_abc123",
  "event": "signup_completed",
  "distinct_id": "user-456",
  "properties": {
    "plan": "premium",
    "$set": {
      "email": "[email protected]"
    }
  },
  "timestamp": "2026-01-15T10:30:00Z",
  "value": 9.99,
  "entityId": "org-789"
}

Response

{
  "status": "ok",
  "eventId": "evt_abc123",
  "customerId": "cust_789",
  "payload": { ... }
}

The response may include additional fields depending on the event type:

• customer -- Returned for identity events
• journey -- Returned for journey lifecycle events
• usage -- Returned for $feature_used events with remaining balance
• featuresMatched -- Count of matched features for custom events
• deduped -- true if the event UUID was already processed

POST /batch

Submit multiple events in a single request. The request body must be gzip-compressed.

Request headers

Content-Encoding: gzip
Content-Type: application/json

Request body (before compression)

{
  "apiKey": "nux_live_abc123",
  "batch": [
    {
      "event": "page_viewed",
      "distinct_id": "user-456",
      "properties": { "page": "pricing" },
      "timestamp": "2026-01-15T10:30:00Z"
    },
    {
      "event": "button_clicked",
      "distinct_id": "user-456",
      "properties": { "button": "subscribe" },
      "timestamp": "2026-01-15T10:30:05Z"
    }
  ]
}

Each event in the batch uses the same fields as POST /event (minus apiKey).

Response

{
  "status": "success",
  "processed": 2,
  "failed": 0,
  "total": 2
}

If some events fail, the response status is "partial" and includes an errors array with the index and error message for each failure. Individual failures do not abort the batch.

POST /profile

Fetch the runtime profile for a user. The profile contains campaigns, segments, flows, features, experiment assignments, and active journeys.

Request body

{
  "apiKey": "nux_live_abc123",
  "distinct_id": "user-456",
  "locale": "en-US"
}

Response

{
  "status": "ok",
  "campaigns": [ ... ],
  "segments": [ ... ],
  "flows": [ ... ],
  "customer": {
    "id": "cust_789",
    "properties": { ... },
    "entitlements": { ... },
    "segments": { ... }
  },
  "experiments": {
    "pricing_test": {
      "experimentKey": "pricing_test",
      "variantKey": "variant_b",
      "status": "running",
      "isHoldout": false
    }
  },
  "features": [ ... ],
  "journeys": [ ... ]
}

If distinct_id is omitted, the response includes only app-level configuration (campaigns, segments, flows) without customer-specific data.

POST /entitled

Check whether a user has access to a feature or product.

Request body

{
  "apiKey": "nux_live_abc123",
  "customerId": "user-456",
  "featureId": "premium_export"
}

Response (feature check)

{
  "status": "ok",
  "entitled": true,
  "feature": {
    "id": "premium_export",
    "type": "boolean"
  }
}

For metered features, the response includes balance information.

POST /purchase

Sync a purchase transaction from a payment provider.

Request body (App Store)

{
  "apiKey": "nux_live_abc123",
  "type": "appstore",
  "distinct_id": "user-456",
  "transactionJWS": "eyJhbGciOi..."
}

Additional fields depend on the purchase type. The SDK handles constructing the correct payload.

GET /flows/:id

Fetch a single flow payload by ID.

GET /flows/ver_abc123?apiKey=nux_live_abc123

Returns the raw published flow definition for rendering in the SDK.

Note: The :id is a published version ID (ver_...) from the profile payload flows array.

GET /status

Check whether app configuration is available.

GET /status?apiKey=nux_live_abc123

Response

{
  "status": "ok",
  "app": {
    "id": "app_123",
    "name": "My App",
    "environment": "live"
  },
  "timestamp": "2026-01-15T10:30:00Z"
}

Returns 503 if app configuration has not been synced to the edge yet.

GET /health

Unauthenticated liveness probe.

{
  "status": "ok",
  "timestamp": "2026-01-15T10:30:00Z"
}

Error handling

All errors follow a consistent format:

{
  "status": "error",
  "message": "Description of the error"
}

Best practices

• Use the SDK instead of calling the API directly. The SDK handles batching, compression, retries, and identity management.
• Always include a uuid field for event idempotency if you are calling the API directly.
• Use POST /batch for high-volume event ingestion. Compress the payload with gzip.
• Check POST /status after initial setup to verify your app configuration has propagated to the edge.

Next steps

• System Events -- Reference for $-prefixed system events
• Webhooks -- Configure App Store webhooks
• iOS SDK Installation -- Get started with the SDK