Skip to main content
POST
/
api
/
public
/
product
/
upsert
/
{promptBlockId}
Upsert products
curl --request POST \
  --url https://api.vambe.me/api/public/product/upsert/{promptBlockId} \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <x-api-key>' \
  --data '
[
  {
    "name": "<string>",
    "description": "<string>",
    "price": 1,
    "external_id": "<string>",
    "metadata": [
      {
        "key": "<string>",
        "value": "<string>"
      }
    ],
    "file_url": "<string>",
    "sku": "<string>"
  }
]
'

​
Overview

Synchronize your entire product catalog with a product block. This endpoint creates new products, updates existing ones, and deletes products not in the request - providing a complete catalog sync. ⚠️ Important: Products not included in the request will be deleted from the block.

​
Use Cases

  • Full Catalog Sync: Replace entire catalog with current inventory
  • Nightly Sync: Complete synchronization from e-commerce platform
  • Inventory Management: Ensure only available products are in catalog
  • Clean Sync: Remove discontinued products automatically

​
Authentication

x-api-key: your_api_key_here

​
Path Parameters

ParameterTypeRequiredDescription
promptBlockIdstringYesProduct block ID to synchronize

​
Request Body

Array of product objects (no limit):
FieldTypeRequiredDescription
namestringYesProduct name
descriptionstringYesNatural language description for AI (max 8192)
pricenumberYesProduct price (positive number)
currencystringYesCurrency code
typestringYesPRODUCT or SERVICE
external_idstringYesYour unique identifier
file_urlstringNoProduct image URL
skustringNoProduct SKU. Falls back to sku key in metadata
metadataarrayYesAdditional product data as key-value pairs
⚠️ DELETES PRODUCTS: Any products in the block that are NOT in this request will be permanently deleted.

​
Example Request

curl --request POST \
  'https://api.vambe.me/api/public/product/upsert/block-abc123' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '[
    {
      "name": "Laptop Pro",
      "description": "High-performance laptop for professionals. 16GB RAM, 512GB SSD, Intel i7 processor. Perfect for development and creative work.",
      "price": 1299.99,
      "currency": "USD",
      "type": "PRODUCT",
      "external_id": "laptop-pro-001",
      "file_url": "https://shop.com/laptop.jpg",
      "sku": "LAPTOP-PRO-001",
      "metadata": [
        { "key": "brand", "value": "TechBrand" },
        { "key": "ram", "value": "16GB" },
        { "key": "storage", "value": "512GB" }
      ]
    }
  ]'

​
Behavior

​
What Happens

  1. Creates: Products with new external_id are created
  2. Updates: Products with existing external_id are updated
  3. Deletes: Products in block but NOT in request are deleted
  4. AI Embeddings: All products are re-indexed for AI search

​
Example Scenario

Before: Block has products A, B, C Request: Send products B (updated), D (new) After: Block has products B (updated), D (new) Deleted: Products A and C

​
Error Responses

Status CodeDescription
400Bad Request - Invalid data
401Unauthorized
403Forbidden
404Product block not found
500Internal Server Error

Headers

​
x-api-key
string
required

API key needed to authorize the request

Path Parameters

​
promptBlockId
string
required

The prompt block ID to upsert the products

Body

application/json

The payload to send with the products

​
name
string
required
Minimum string length: 1
​
description
string
required

In the description you only need to add words that help the AI do a semantic search, avoide placing here prices, links or other type of data that is not natural language

Required string length: 1 - 8192
​
type
enum<string>
required
Available options:
shopify,
vambe,
woocommerce,
axis,
vtex,
jumpseller,
odoo,
tiendanube,
magento,
custom_app
​
currency
enum<string>
required
Available options:
CLP,
USD,
MXN,
BRL,
UF,
ARS,
COP,
UYU,
PEN,
EUR,
HNL,
BOB,
PYG,
GTQ,
NIO,
PAB,
CRC,
DOP,
VES,
BZD,
SRD,
GYD
​
price
number
required
Required range: x > 0
​
external_id
string
required
​
metadata
object[]
required
​
file_url
string
​
sku
string

Response

Products upserted successfully.