Skip to main content
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. Use POST /v1/items/{item_id} to update an existing item.

​
Request

POST /v1/items

{
  "id": "7f3a2c9e",
  "name": "Wireless Headphones",
  "description": "Noise-cancelling Bluetooth headphones.",
  "metadata": {
    "category": "electronics",
    "brand": "Acme",
    "price": 10999,
    "currency": "usd"
  }
}
id is optional. If omitted, NeuronSearchLab generates an opaque ID. The aliases item_id and itemId are also accepted, but only one ID field should be present.
FieldTypeRequiredDescription
idstringnoItem ID such as 7f3a2c9e.
namestringyesHuman-readable item name.
descriptionstringnoText used for embeddings and debugging.
metadataobjectnoJSON object with filterable catalog attributes.
You can also send an array of item objects to create multiple items in one call.

​
Response

{
  "id": "7f3a2c9e",
  "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
}
When the request body is an array, the response is a list envelope (object: "list") whose data array contains every created item. A single-item request returns the item resource directly.

​
Errors

StatusScenario
400Missing body, invalid JSON, missing name, or malformed id
401Missing or invalid Bearer token
403Token does not include neuronsearchlab-api/write
409An item with the requested ID already exists

Authorizations

​
Authorization
string
header
required

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

Body

application/json
​
name
string
required
Minimum string length: 1
Example:

"Wireless Headphones"

​
id
string

Optional public item ID. If omitted, the API generates one.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
Example:

"7f3a2c9e"

​
item_id
string

Snake-case alias for id.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
​
itemId
string

CamelCase alias for id.

Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
​
description
string
Example:

"Noise-cancelling Bluetooth headphones."

​
metadata
object

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

​
id
string
required
Pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$
Example:

"7f3a2c9e"

​
object
enum<string>
required
Available options:
item
​
name
string
required
Example:

"Wireless Headphones"

​
description
string
required
Example:

"Noise-cancelling Bluetooth headphones."

​
metadata
object
required

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

Example:
{
  "category": "electronics",
  "brand": "Acme",
  "price": 10999,
  "currency": "usd"
}
​
active
boolean
required
Example:

true

​
created
integer<int64> | null
required

Unix timestamp in seconds.

Example:

1777478400

​
updated_at
integer<int64> | null
required

Unix timestamp in seconds.

Example:

1777478500