Submit events

curl --request POST \
  --url https://api.neuronsearchlab.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
'

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "purchase": {
        "amount": 4999,
        "currency": "usd"
      },
      "session_id": null,
      "request_id": null,
      "context_id": 101,
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": 101,
        "purchase": {
          "amount": 4999,
          "currency": "usd"
        }
      },
      "occurred_at": 1777478400,
      "created": 1777478405
    }
  ],
  "has_more": false,
  "url": "/v1/events",
  "inserted": 1,
  "processed": 1,
  "session": {
    "with_session_id": 0,
    "with_request_id": 0
  },
  "embedding_refresh": {
    "users_in_batch": 1,
    "enqueued": true,
    "mode": "async",
    "min_seconds": 30
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Validation error",
    "details": {
      "fieldErrors": {
        "name": [
          "Required"
        ]
      }
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized_no_client_id_in_jwt",
    "message": "Unauthorized: No client ID in JWT"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

POST

events

curl --request POST \
  --url https://api.neuronsearchlab.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
'

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "purchase": {
        "amount": 4999,
        "currency": "usd"
      },
      "session_id": null,
      "request_id": null,
      "context_id": 101,
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": 101,
        "purchase": {
          "amount": 4999,
          "currency": "usd"
        }
      },
      "occurred_at": 1777478400,
      "created": 1777478405
    }
  ],
  "has_more": false,
  "url": "/v1/events",
  "inserted": 1,
  "processed": 1,
  "session": {
    "with_session_id": 0,
    "with_request_id": 0
  },
  "embedding_refresh": {
    "users_in_batch": 1,
    "enqueued": true,
    "mode": "async",
    "min_seconds": 30
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Validation error",
    "details": {
      "fieldErrors": {
        "name": [
          "Required"
        ]
      }
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized_no_client_id_in_jwt",
    "message": "Unauthorized: No client ID in JWT"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Description

Records user behavior that powers personalization, attribution, analytics, and model training. event_id must be the non-zero integer shown for an event in your dashboard. Event names such as "click" are display labels and are not accepted as identifiers.

Request

POST /v1/events

{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "occurred_at": 1777478400,
  "metadata": {
    "surface": "home_feed",
    "amount": 4999,
    "currency": "usd"
  }
}

Field	Type	Required	Description
`user_id`	string	yes	End-user identifier.
`item_id`	integer	yes, except on a search event	Item ID returned by NSL ingestion, such as `3187`.
`context_id`	integer	no	Context ID generated when the context is created in the dashboard.
`event_id`	integer	yes, except on a search event	Event ID generated when the event is created in dashboard Event configuration.
`query`	string	no	What the user searched for. With no `item_id`, the event is a search event. With an `item_id`, it is kept as the search the user reached the item from.
`result_item_ids`	integer[]	no	Search events only: item IDs your engine showed for `query`, in rank order.
`session_id`	string	no	Session identifier for attribution and analytics.
`request_id`	string	no	Recommendation request ID returned by `GET /v1/recommendations`.
`placement`	string	no	Surface or placement where the event occurred.
`occurred_at`	integer	no	Unix timestamp for when the action happened. Defaults to ingestion time.
`metadata`	object	no	Additional event context.

Search events

A search is an event with a query and no item_id. It weighs into that user’s recommendations by the weight of its event type, like any other event. event_id is optional: it defaults to the event your search signal is bound to, and one named Search (weight 25) is created on first use when nothing is bound yet. The items in result_item_ids are stored as impressions, never as items the user chose.

{
  "user_id": "user-abc123",
  "query": "waterproof trail shoes",
  "result_item_ids": [3187, 3190, 3201],
  "session_id": "session-42"
}

To record a search and get recommendations back in one call, send it to POST /v1/search with result_item_ids instead. Camel-case aliases userId, itemId, eventId, contextId, sessionId, requestId, and resultItemIds remain available, but all identifier aliases carry the same integer values. Event batches are capped at 200 events per request by default.

Response

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "session_id": null,
      "request_id": null,
      "context_id": 101,
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": 101
      },
      "occurred_at": 1777478400,
      "created": 1777478405
    }
  ],
  "has_more": false,
  "url": "/v1/events",
  "inserted": 1,
  "processed": 1,
  "session": {
    "with_session_id": 0,
    "with_request_id": 0
  },
  "embedding_refresh": {
    "users_in_batch": 1,
    "enqueued": true,
    "mode": "async",
    "min_seconds": 30
  }
}

The response also returns ingestion stats (inserted, processed, session) and an embedding_refresh block describing the async user-embedding refresh job that was enqueued for the affected users.

Errors

Status	Scenario
`400`	Missing required fields, invalid JSON, unknown item, unknown event type, an empty `query` on an event with no item, or `result_item_ids` on an item event
`401`	Missing or invalid Bearer token
`403`	Token does not include `neuronsearchlab-api/write`

Authorizations

Authorization

string

header

required

The access token received from the authorization server in the OAuth 2.0 flow.

FlowClient Credentials

Token URL: https://auth.neuronsearchlab.com/oauth2/token

Scopes1

neuronsearchlab-api/write

Create, update, and delete items; submit events.

Body

application/json

object
object[]

A user ID is always required. An item event needs a non-zero dashboard event_id and a positive NSL-generated item_id. A search event sends a query and no item_id; its event_id is optional and defaults to the event your search signal is bound to. context_id is a positive NSL-generated integer when supplied.

user_id

string

End-user identifier.

Example:

"user-abc123"

userId

string

CamelCase alias for user_id.

item_id

integer

Item ID returned by NSL ingestion. Required unless the event is a search (a query with no item).

Required range: x >= 1

Example:

3187

itemId

integer

CamelCase alias for item_id.

Required range: x >= 1

query

string

What the user searched for. An event with a query and no item_id is a search event: it steers the user's recommendations by the weight of its event type, and event_id defaults to the event your search signal is bound to. With an item_id, the query is kept on the item event as the search the user reached it from. Longer queries are cut to 256 characters.

Maximum string length: 256

Example:

"waterproof trail shoes"

result_item_ids

integer[]

Item IDs your own search engine showed for query, in rank order. Recorded as impressions, not as items the user chose. Only accepted on a search event; the first 50 are kept.

Maximum array length: 50

Required range: x >= 1

Example:

[3187, 3190, 3201]

resultItemIds

integer[]

CamelCase alias for result_item_ids.

Required range: x >= 1

event_id

integer

Non-zero event ID shown in dashboard Event configuration. Optional on a search event, where it defaults to your Search event.

eventId

integer

CamelCase alias for event_id.

session_id

string

Optional session identifier.

sessionId

string

CamelCase alias for session_id.

request_id

string<uuid>

Recommendation request ID to attribute this event to.

requestId

string<uuid>

CamelCase alias for request_id.

context_id

integer

Optional context ID created in the dashboard.

Required range: x >= 1

Example:

101

contextId

integer

CamelCase alias for context_id.

Required range: x >= 1

Example:

101

placement

string

Surface or placement where the event happened.

Example:

"home_feed"

metadata

object

Arbitrary JSON object used for filtering, ranking, and debugging.

Example:

{
  "category": "electronics",
  "brand": "Acme",
  "price": 10999,
  "currency": "usd"
}

occurred_at

Event occurrence timestamp. Numeric values below 1e12 are interpreted as Unix seconds.

Example:

1777478400

occurredAt

CamelCase alias for occurred_at.

timestamp

Legacy timestamp alias.

client_ts

Legacy client timestamp alias.

clientTs

CamelCase alias for client_ts.

Response

Inserted events

object

enum<string>

required

Available options:

list

data

object[]

required

Show child attributes

has_more

boolean

required

url

string

required

inserted

integer

required

Required range: x >= 0

processed

integer

required

Required range: x >= 0

session

object

required

Show child attributes

embedding_refresh

object

required

Show child attributes

next_cursor

string | null

Overview

Authentication

Items

Events

Recommendations

Search

Description

Request

Search events

Response

Errors

Authorizations

Body

Response

​Description

​Request

​Search events

​Response

​Errors

Authorizations

Body

Response

Description

Request

Search events

Response

Errors