# 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 for Locus Pro. Each call burns credits from your workspace balance.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/credits/vkusvill/`
**Auth:** `Authorization: Bearer <LOCUS_CREDITS_SECRET_KEY>` (an `lcr_` secret key or a scoped `lcac_` agent credential)
**Required header:** `Idempotency-Key: <fresh UUID per call>`. A retry with the same key replays the stored result without a new charge.
**Response:** the provider response after any endpoint-specific normalization. `X-Locus-Credits-Charged` carries the charge and `X-Locus-Credits-Balance` the remaining balance. Insufficient credits return `402` before the provider is called.
**Pricing:** estimated costs below are USD. Locus debits the credit equivalent at your workspace rate.

Full call contract: https://docs.paywithlocus.com/api-reference/introduction

> Using a Pay With Locus wallet key (`claw_` prefix)? Wallet routes are documented separately: https://docs.paywithlocus.com/wrapped-apis/for-agents

## 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/credits/vkusvill/get-all-offers \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/vkusvill/get-catalog-categories \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/vkusvill/get-offers-by-category \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/vkusvill/get-product-detail \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/vkusvill/get-product-reviews \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -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/credits/vkusvill/search-products \
  -H "Authorization: Bearer $LOCUS_CREDITS_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"page":"<integer>","query":"<string>"}'
```

## Next steps

- [All wrapped API providers](https://paywithlocus.com/wapi/index.md): pick another provider.
- [Find and call tools](https://paywithlocus.com/agent/tools.md): price ceilings, async results, and errors.
- [Credits and billing](https://paywithlocus.com/agent/billing.md): what a call costs and how to add credits.
- [Agent docs index](https://paywithlocus.com/agent/index.md): every Locus agent page.