Skip to main content

Partner API

The VTO Partner API is a REST API for managing your Virtual Try-On catalog from your own systems. With it, you can:

  • Build and manage your catalog: create brands, categories, products and variants.
  • Upload images: manage the visual assets of your VTO experience.
  • Configure digitalization: define how each variant looks in the try-on (makeup type, color, opacity).
  • Control stock: mark variants in stock or out of stock in real time. See Stock and status.
  • Automate updates: keep your existing product database in sync with PulpoAR.

Changes made with the Partner API are global: they affect all users. To change data for a single user session, use SDK actions.

Open the interactive API reference →

Prefer no code?

You can manage the catalog in Studio, or in bulk with Excel. See Catalog Manager. To create an API key, see API keys.

Base URL​

https://api.pulpoar.com

All endpoints are under /vto-partner/, and most are scoped by your project key:

https://api.pulpoar.com/vto-partner/{project_key}/...

project_key can be your project slug or UUID.

Authentication​

Send your API key in the X-API-Key header with every request:

curl https://api.pulpoar.com/vto-partner/<project-key>/products \
--header 'X-API-Key: <api-key>'

Create your API key in Studio. See API keys.

Keep your key secret

Call the Partner API only from your server. Never put your API key in a website, mobile app or public repository.

Endpoints​

ResourceMethodEndpoint
ImagesPOST, GET/vto-partner/{project_key}/images
BrandsPOST, GET, PATCH/vto-partner/{project_key}/brands
CategoriesPOST, GET, PATCH/vto-partner/{project_key}/categories
ProductsPOST, GET, PATCH/vto-partner/{project_key}/products
VariantsPOST, GET, PATCH/vto-partner/{project_key}/variants
Single variantGET/vto-partner/{project_key}/variants/{variant_key}
StockGET/vto-partner/{project_key}/stock
StockPATCH/vto-partner/stock

POST endpoints use upsert semantics: if an item with the same slug exists, it's updated instead of duplicated.

Rate limits​

  • 500 requests per 15 minutes per API key.
  • Every response includes the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers.
  • When you exceed the limit, the API returns 429 with retry_after (seconds until the limit resets).

Batch limits​

EndpointMax items per request
Stock update200
Variants update100

Pagination​

List endpoints accept limit and offset, and return a pagination object:

{
"total": 100,
"limit": 100,
"offset": 0,
"has_next": false,
"next_offset": null
}

Errors​

Errors return success: false with a message and details:

{
"success": false,
"error": "Validation failed",
"details": ["Invalid stock_status value"]
}

Downloads​

Next steps​

  • Catalog workflow: build a catalog from scratch, step by step.
  • API reference: every endpoint, with request and response schemas, and an interactive "try it" panel.