Create or update search item

Create or update one item inside a search collection for the authenticated business. Upserts by business + collection + external_id.

POST/api/external/v2/search/item

Authentication

This endpoint authenticates with an API key via the X-API-Key header (ek_live_... format), instead of the bearer token used in the rest of the reference.

Request body

Parameter	Type	Required	Description
`collection_id`	String (UUID)	Required	UUID of the target search collection.
`external_id`	String	Required	External identifier unique within the collection.
`item`	Object	Required	Full JSON object to store on the item (payload).
`embedding_json`	Object	Optional	Optional JSON object used as the embedding payload; overrides the collection config when provided.
`active`	Boolean	Optional	Whether the item stays active after the upsert (defaults to true).

Example request

bash

curl -X POST "https://eclectic-api-537143970188.us-central1.run.app/api/external/v2/search/item" \
  -H "X-API-Key: ek_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_id": "35f6f8cc-b550-4278-a2ea-099f3a4e0730",
    "external_id": "sku-12345",
    "item": {
      "name": "Blue T-Shirt",
      "price": 19.99,
      "description": "100% cotton blue t-shirt"
    },
    "active": true
  }'

Example response

json

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "collection_id": "35f6f8cc-b550-4278-a2ea-099f3a4e0730",
  "external_id": "sku-12345",
  "source": "api",
  "operation": "created",
  "is_active": true,
  "embedding_regenerated": true,
  "payload": {
    "name": "Blue T-Shirt",
    "price": 19.99,
    "description": "100% cotton blue t-shirt"
  },
  "embedding_json": {
    "name": "Blue T-Shirt",
    "description": "100% cotton blue t-shirt"
  },
  "created_at": "2024-09-23T20:09:10Z",
  "updated_at": "2024-09-23T20:09:10Z"
}

Notes

If you don't send embedding_json, it is derived from the collection's configured embedding_fields.
The operation field indicates whether the item was created, updated or unchanged.
Possible errors: 400 (validation), 401 (invalid or missing API key).