# Vkusvill — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Search and browse products from VkusVill, a Russian grocery retailer, including detailed product information, customer reviews, current offers, and category-filtered offer listings. Get real-time access to product categories, pricing, and availability across the store's full range of items.

**Category:** Food & Dining | **Website:** [vkusvill.ru/](https://vkusvill.ru/) | **Docs:** [parse.bot/marketplace/954fef27-e227-4a53-acde-98a60bd2b2eb/vkusvill-ru-api](https://parse.bot/marketplace/954fef27-e227-4a53-acde-98a60bd2b2eb/vkusvill-ru-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_all_offers

Retrieves all currently active offers and discounted products across all categories. Returns product cards with id, name, price, weight, rating, labels, and URL. No pagination — returns the top offers displayed on the offers page.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/get_all_offers \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_catalog_categories

Retrieves all top-level product categories from the VkusVill catalog. Returns category names, slugs, and full URLs. Categories include both permanent departments (dairy, meat, beverages) and seasonal/curated sets. No pagination — all categories returned in a single response.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/get_catalog_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_offers_by_category

Retrieves current offers filtered by a category slug. Category slugs correspond to the offers section of the site, not the catalog categories. Common offer category slugs include 'morozhenoe' (ice cream), 'molochnye-produkty-yaytso' (dairy).

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category_slug` | string | Yes | Category slug for offer filtering (e.g. 'morozhenoe', 'molochnye-produkty-yaytso'). These are offer-section categories. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/get_offers_by_category \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category_slug":"<string>"}'
```

### get_product_detail

Retrieves full product details by product slug. Returns name, price, weight, rating, review count, description, ingredients list, and nutritional information (protein, fat, carbs, calories per 100g). Product slugs can be extracted from product URLs returned by search or listing endpoints.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `product_slug` | string | Yes | Product slug from URL path (e.g. 'moloko-3-173'). Available from search_products or catalog results[*].url as the last path segment without trailing slash. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/get_product_detail \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"product_slug":"<string>"}'
```

### get_product_reviews

Retrieves customer reviews for a product by its numeric ID. Returns up to 10 reviews per page with author name, star rating (1-5), date, and review text. Product IDs are available from search_products or catalog listing results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination, starting at 1. |
| `product_id` | string | Yes | Numeric product ID (e.g. '173', '36296'). Available from search_products results[*].id. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/get_product_reviews \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","product_id":"<string>"}'
```

### search_products

Searches for products by text query (typically in Russian). Returns paginated product cards with id, name, price, weight, rating, labels, and URL. Results are ordered by relevance. Each page returns up to ~30 products.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `page` | integer | No | Page number for pagination, starting at 1. |
| `query` | string | Yes | Search query string in Russian (e.g. 'молоко', 'хлеб', 'сыр'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-vkusvill-ru-api-954fef27/search_products \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```