Create products

curl --request POST \
  --url https://api.vambe.me/api/public/product/create/{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>"
  }
]
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      name: '<string>',
      description: '<string>',
      price: 1,
      external_id: '<string>',
      metadata: [{key: '<string>', value: '<string>'}],
      file_url: '<string>',
      sku: '<string>'
    }
  ])
};

fetch('https://api.vambe.me/api/public/product/create/{promptBlockId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vambe.me/api/public/product/create/{promptBlockId}"

payload = [
    {
        "name": "<string>",
        "description": "<string>",
        "price": 1,
        "external_id": "<string>",
        "metadata": [
            {
                "key": "<string>",
                "value": "<string>"
            }
        ],
        "file_url": "<string>",
        "sku": "<string>"
    }
]
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

POST

api

public

product

create

{promptBlockId}

Create products

curl --request POST \
  --url https://api.vambe.me/api/public/product/create/{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>"
  }
]
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<x-api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify([
    {
      name: '<string>',
      description: '<string>',
      price: 1,
      external_id: '<string>',
      metadata: [{key: '<string>', value: '<string>'}],
      file_url: '<string>',
      sku: '<string>'
    }
  ])
};

fetch('https://api.vambe.me/api/public/product/create/{promptBlockId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vambe.me/api/public/product/create/{promptBlockId}"

payload = [
    {
        "name": "<string>",
        "description": "<string>",
        "price": 1,
        "external_id": "<string>",
        "metadata": [
            {
                "key": "<string>",
                "value": "<string>"
            }
        ],
        "file_url": "<string>",
        "sku": "<string>"
    }
]
headers = {
    "x-api-key": "<x-api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

Overview

Create or update products in a product block WITHOUT deleting existing ones. This endpoint is additive - it only creates new products and updates existing ones based on external_id, leaving other products unchanged. Perfect for incrementally adding products to your catalog without affecting the rest.

Use Cases

Add New Products: Add products as they become available
Update Specific Products: Update only certain products without touching others
Incremental Sync: Sync new/changed products without full catalog refresh
Safe Updates: Modify products without risking deletion of others

Authentication

x-api-key: your_api_key_here

Path Parameters

Parameter	Type	Required	Description
`promptBlockId`	string	Yes	Product block ID to add products to

Request Body

Array of product objects (1-2000 products):

Field	Type	Required	Description
`name`	string	Yes	Product name
`description`	string	Yes	Natural language description for AI (max 8192 chars)
`price`	number	Yes	Product price (must be positive)
`currency`	string	Yes	Currency code (USD, EUR, CLP, etc.)
`type`	string	Yes	Product type (PRODUCT or SERVICE)
`external_id`	string	Yes	Your unique identifier for this product
`file_url`	string	No	URL to product image or file
`sku`	string	No	Product SKU. Falls back to `sku` key in metadata
`metadata`	array	Yes	Array of key-value pairs for additional data

Description Best Practice: Use natural language that helps AI understand the product. Avoid URLs, prices (already in price field), or structured data. Focus on features, benefits, and use cases.

Example Request

curl --request POST \
  'https://api.vambe.me/api/public/product/create/block-abc123' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: your_api_key_here' \
  --data-raw '[
    {
      "name": "Premium Coffee Beans",
      "description": "High-quality arabica coffee beans from Colombia. Rich flavor with hints of chocolate and caramel. Perfect for espresso or filter coffee.",
      "price": 24.99,
      "currency": "USD",
      "type": "PRODUCT",
      "external_id": "coffee-premium-001",
      "file_url": "https://example.com/images/coffee.jpg",
      "sku": "COFFEE-PREM-001",
      "metadata": [
        { "key": "origin", "value": "Colombia" },
        { "key": "roast", "value": "Medium" },
        { "key": "weight", "value": "500g" }
      ]
    },
    {
      "name": "Delivery Service",
      "description": "Fast delivery service for orders. Next-day delivery available in selected areas. Professional handling of all packages.",
      "price": 5.00,
      "currency": "USD",
      "type": "SERVICE",
      "external_id": "service-delivery-001",
      "metadata": [
        { "key": "delivery_time", "value": "1-2 days" },
        { "key": "coverage", "value": "Nationwide" }
      ]
    }
  ]'

Example Response

{
  "created": 2,
  "updated": 0,
  "products": [
    {
      "id": "prod-uuid-001",
      "external_id": "coffee-premium-001",
      "name": "Premium Coffee Beans"
    },
    {
      "id": "prod-uuid-002",
      "external_id": "service-delivery-001",
      "name": "Delivery Service"
    }
  ]
}

Product Types

Type	Use For
`PRODUCT`	Physical or digital products
`SERVICE`	Services, consultations, subscriptions

Currency Codes

Supported currencies: USD, EUR, GBP, CLP, MXN, COP, ARS, PEN, BRL, and more.

Create vs Upsert

Feature	Create (This Endpoint)	Upsert
New Products	✅ Creates	✅ Creates
Existing Products	✅ Updates (by external_id)	✅ Updates
Other Products	✅ Keeps unchanged	❌ Deletes if not in request
Use When	Adding/updating specific items	Full catalog sync

Error Responses

Status Code	Description
400	Bad Request - Invalid product data
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found - Product block not found
500	Internal Server Error

GET /api/public/product/product-blocks - List available blocks
POST /api/public/product/upsert/ - Full catalog sync
POST /api/public/product/delete/ - Delete products

Headers

x-api-key

string

required

API key needed to authorize the request

Path Parameters

promptBlockId

string

required

The prompt block ID to create the products

Body

application/json

The payload to send with the products

Required array length: 1 - 2000 elements

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,

mercado_libre,

custom_app,

prestashop

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

Show child attributes

file_url

string

sku

string

Response

Products created successfully.

​Overview

​Use Cases

​Authentication

​Path Parameters

​Request Body

​Example Request

​Example Response

​Product Types

​Currency Codes

​Create vs Upsert

​Error Responses

​Related Endpoints

Headers

Path Parameters

Body

Response

Overview

Use Cases

Authentication

Path Parameters

Request Body

Example Request

Example Response

Product Types

Currency Codes

Create vs Upsert

Error Responses

Related Endpoints