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 →
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.
Call the Partner API only from your server. Never put your API key in a website, mobile app or public repository.
Endpoints
| Resource | Method | Endpoint |
|---|---|---|
| Images | POST, GET | /vto-partner/{project_key}/images |
| Brands | POST, GET, PATCH | /vto-partner/{project_key}/brands |
| Categories | POST, GET, PATCH | /vto-partner/{project_key}/categories |
| Products | POST, GET, PATCH | /vto-partner/{project_key}/products |
| Variants | POST, GET, PATCH | /vto-partner/{project_key}/variants |
| Single variant | GET | /vto-partner/{project_key}/variants/{variant_key} |
| Stock | GET | /vto-partner/{project_key}/stock |
| Stock | PATCH | /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-RemainingandX-RateLimit-Resetheaders. - When you exceed the limit, the API returns
429withretry_after(seconds until the limit resets).
Batch limits
| Endpoint | Max items per request |
|---|---|
| Stock update | 200 |
| Variants update | 100 |
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
- OpenAPI spec (JSON): import it into Postman, Insomnia or your own tools.
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.