Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt

Use this file to discover all available pages before exploring further.

The NeuronSearchLab Core API is the data-plane surface for catalog ingestion, event ingestion, and recommendation serving.
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
itemitm_7f3a2c9eCatalog item available for recommendation
eventevt_12345User interaction event
recommendationrec_itm_7f3a2c9eRanked recommendation result
listn/aCursor-paginated list envelope
Resource IDs use short prefixes so logs and payloads are easier to scan. 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. The Core API also accepts legacy ctx_ aliases such as ctx_101 and normalizes them in recommendation explanations and served-recommendation telemetry.

​
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=itm_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
Each endpoint supports OPTIONS preflight with standard CORS headers.