Record an event

Record a customer action or update customer properties.

POSThttps://i.nuxie.ai/event

Record a customer action, update customer properties, or send an event used by an Experience trigger. Use a stable UUID so retries do not record the action twice.

Request body

apiKeybodystringrequired

Publishable key for the app platform. A pk_test_ key selects test data; a pk_live_ key selects live data. Copy it from Connect your app.

eventbodystringrequired

Non-empty event name. Names starting with $ are system events, recorded by the SDK and platform.

distinct_idbodystringrequired

The identified or anonymous customer ID your app supplies to the SDK, rather than Nuxie’s internal customer record ID. See Customer identifiers.

propertiesbodyobject

Values describing this event. Supports the customer-property directives below.

timestampbodystring

ISO 8601 timestamp for when the event happened.

uuidbodystring

Valid UUID for the event. Required unless you supply idempotency_key; reuse the same value for retries.

idempotency_keybodystring

Alternative to uuid, also a valid UUID.

valuebodynumber

Numeric value associated with the event.

entityIdbodystring

Entity identifier for entity-scoped Feature activity.

$anon_distinct_idbodystring

Prior anonymous identity during an identify merge.

Customer properties

An event’s properties describe that occurrence. These directives inside properties also update the customer profile:

Directive	Value	Behavior
`$set`	Object	Set or replace customer properties
`$set_once`	Object	Set properties only when they don’t already exist
`$unset`	Array of property names	Remove customer properties
`$increment`	Object of numeric amounts	Add each amount to the current numeric value, starting from zero when absent

For example:

{
  "source": "settings",
  "$set": { "plan": "pro" },
  "$set_once": { "signup_source": "referral" },
  "$unset": ["onboarding_step"],
  "$increment": { "exports_created": 1 }
}

Use one directive per property in a request. See Customer properties for targeting with these values.

Response

statusstringrequired

ok for an accepted ordinary app event.

eventIdstringrequired

Event UUID.

customerIdHintstringrequired

Nuxie customer record hint; keep using your own customer ID in requests.

acceptedintegerrequired

Number of accepted events: 1.

queuedbooleanrequired

true confirms the event was accepted for processing.

payloadobjectrequired

Supported event fields after normalization.

Customer profiles, analytics, and server-side delivery update as the event is processed. The response confirms receipt, rather than completion of those updates.

Reuse the event UUID if a request times out. A new UUID records another occurrence. To change paid access or spend units, use the purchase and Feature usage endpoints; an analytics event alone does not authorize those changes.

curl https://i.nuxie.ai/event \
  --header 'Content-Type: application/json' \
  --data '{
  "apiKey": "pk_test_example",
  "event": "export_limit_reached",
  "distinct_id": "user-456",
  "properties": {
    "limit": 10,
    "$set": { "plan": "free" }
  },
  "timestamp": "2026-08-21T12:00:00Z",
  "uuid": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"
}'

{
  "status": "ok",
  "eventId": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410",
  "customerIdHint": "customer-record-id",
  "accepted": 1,
  "queued": true,
  "payload": {
    "apiKey": "pk_test_example",
    "event": "export_limit_reached",
    "distinct_id": "user-456",
    "properties": {
      "limit": 10,
      "$set": { "plan": "free" }
    },
    "timestamp": "2026-08-21T12:00:00Z",
    "uuid": "018f55a9-9ec4-7d7a-9b4a-1dbe8cc58410"
  }
}