curl --request POST \
--url https://api.neuronsearchlab.com/v1/items \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "7f3a2c9e",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
}
'{
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme"
},
"active": true,
"created": 1777478400,
"updated_at": 1777478500
}Items
Create items
Create catalog items for recommendation.
POST
/
v1
/
items
curl --request POST \
--url https://api.neuronsearchlab.com/v1/items \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"id": "7f3a2c9e",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
}
'{
"id": "7f3a2c9e",
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme"
},
"active": true,
"created": 1777478400,
"updated_at": 1777478500
}Description
Creates one or more catalog items. NeuronSearchLab generates each positive integer item ID. Store the returnedid; use it for events and POST /v1/items/{item_id} updates.
Request
POST /v1/items
{
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
}
id, item_id, or itemId. IDs are generated by NeuronSearchLab during ingestion.
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Human-readable item name. |
description | string | no | Text used for embeddings and debugging. |
metadata | object | no | JSON object with filterable catalog attributes. |
Response
{
"id": 3187,
"object": "item",
"name": "Wireless Headphones",
"description": "Noise-cancelling Bluetooth headphones.",
"metadata": {
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
},
"active": true,
"created": 1777478400,
"updated_at": 1777478400
}
object: "list") whose data array contains every created item. A single-item request returns the item resource directly.
Errors
| Status | Scenario |
|---|---|
400 | Missing body, invalid JSON, missing name, or a caller-supplied item ID |
401 | Missing or invalid Bearer token |
403 | Token does not include neuronsearchlab-api/write |
Authorizations
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[]
Minimum string length:
1Example:
"Wireless Headphones"
Example:
"Noise-cancelling Bluetooth headphones."
Arbitrary JSON object used for filtering, ranking, and debugging.
Example:
{
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
Response
Created item or created item list
- Option 1
- Option 2
Pattern:
^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$Example:
"7f3a2c9e"
Available options:
item Example:
"Wireless Headphones"
Example:
"Noise-cancelling Bluetooth headphones."
Arbitrary JSON object used for filtering, ranking, and debugging.
Example:
{
"category": "electronics",
"brand": "Acme",
"price": 10999,
"currency": "usd"
}
Example:
true
Unix timestamp in seconds.
Example:
1777478400
Unix timestamp in seconds.
Example:
1777478500
Was this page helpful?