Skip to main content
The NeuronSearchLab Core API is the data-plane surface for catalog ingestion, event ingestion, recommendation serving, and query-driven search.
Use this API when your application backend needs to create catalog items, submit user events, or fetch recommendations for your app experience. If you are looking to automate console data, tenant configuration, training, analytics, billing, or other control-plane workflows, use the Platform API instead.

​
Core API vs Platform API

The Core API belongs behind your own server-side boundary. Do not expose OAuth client credentials, access tokens, or direct Core API calls from a browser or mobile client.

​
Base URLs

https://api.neuronsearchlab.com
https://auth.neuronsearchlab.com/oauth2/token
Use the Core API domain for resource calls and the auth domain for token exchange. The token endpoint is unauthenticated, lives on the auth subdomain, and is rate-limited independently from resource traffic.

​
Authentication

Protected endpoints require a Bearer token: 
Authorization: Bearer <access_token>
Tokens are issued with OAuth 2.0 client credentials. Access tokens expire after 3600 seconds by default and should be refreshed by your backend before expiry. Required scopes:
ScopeAccess
neuronsearchlab-api/readRead recommendations, items, and events
neuronsearchlab-api/writeCreate/update/delete items and submit events
The slash-delimited scope names are the current Cognito-issued values. Client libraries should treat the full string as opaque and split scopes only on spaces.

​
Object Model

Every resource response includes a read-only object discriminator.
ObjectExample IDDescription
item7f3a2c9eCatalog item available for recommendation
event12345User interaction event
recommendation7f3a2c9eRanked recommendation result
listn/aCursor-paginated list envelope
Resource IDs are opaque strings unless an endpoint documents a numeric server-generated ID. Contexts are console configuration records, not Core API resources; pass the numeric console context ID, for example 101, when a recommendation request should use one.

​
Timestamps

Datetime fields are Unix timestamps in integer seconds.
  • Use created for resource creation time.
  • Use <verb>ed_at for action-derived timestamps such as occurred_at.
  • Use future-tense fields such as expires_at for future scheduled times.
  • Do not use created_at in Core API payloads.

​
Pagination

List endpoints use cursor-style pagination: 
GET /v1/items?limit=20&starting_after=7f3a2c9e
List responses use this envelope: 
{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/items"
}
limit defaults to 20 and is capped at 100.

​
Errors

Errors use a consistent JSON envelope: 
{
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "Required parameter 'user_id' is missing."
  }
}
Common statuses are 400 for invalid requests, 401 for missing or invalid credentials, 403 for insufficient scope, 404 for missing resources, 409 for create conflicts, 429 for rate limits, and 500 for unexpected server errors.

​
Endpoints

MethodPathScope
POST/v1/itemsneuronsearchlab-api/write
GET/v1/itemsneuronsearchlab-api/read
GET/v1/items/{item_id}neuronsearchlab-api/read
POST/v1/items/{item_id}neuronsearchlab-api/write
PATCH/v1/items/{item_id}neuronsearchlab-api/write
DELETE/v1/items/{item_id}neuronsearchlab-api/write
POST/v1/eventsneuronsearchlab-api/write
GET/v1/eventsneuronsearchlab-api/read
GET/v1/events/{event_id}neuronsearchlab-api/read
GET/v1/recommendationsneuronsearchlab-api/read
POST/v1/searchneuronsearchlab-api/read
Each endpoint supports OPTIONS preflight with standard CORS headers.