# Kolesa — 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 for cars, spare parts, and other vehicles across Kazakhstan's largest marketplace, and retrieve detailed listing information including makes, models, and cities. Browse thousands of automotive listings to find exactly what you're looking for with comprehensive filtering and product details.

**Category:** Automotive | **Website:** [kolesa.kz/](https://kolesa.kz/) | **Docs:** [parse.bot/marketplace/4a328b2b-4054-4be3-b44e-8871186d5a87/kolesa-kz-api](https://parse.bot/marketplace/4a328b2b-4054-4be3-b44e-8871186d5a87/kolesa-kz-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-kolesa-kz-api-4a328b2b/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_car_listing

Retrieve full details of a single car listing by its numeric ID. Returns vehicle parameters (city, generation, body type, engine volume, transmission, drive, color, customs status), seller information, photos, description text, and view/publish stats. The listing_id comes from search_cars results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `listing_id` | string | Yes | Numeric listing ID from search_cars results (e.g. '222544046'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/get_car_listing \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"listing_id":"<string>"}'
```

### get_cities

Retrieve all regions and cities available for geographic filtering. Returns Kazakhstan oblasts and major cities with URL-safe aliases used in search endpoints. The list is unpaginated and stable.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/get_cities \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_makes

Retrieve the full catalog of car makes (brands) available on Kolesa.kz. Each make includes a numeric ID (used by get_models), a URL-safe slug, popularity count, icon URL, and search synonyms. The list is unpaginated and stable — use it to resolve user-facing brand names to IDs or slugs before calling other endpoints.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/get_makes \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_models

Retrieve car models belonging to a specific make/brand. Returns model names, URL-safe slugs, body-group classification, popularity counts, and synonyms. The mark_id comes from get_makes results. The list is unpaginated.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mark_id` | string | Yes | The numeric make/brand ID obtained from get_makes endpoint (e.g. '176' for Toyota, '79' for Hyundai, '18' for BMW). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/get_models \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mark_id":"<string>"}'
```

### search_cars

Search car listings with make, model, region, price range, year range, and many other filters. Returns paginated summaries including price, city, posting date, and thumbnail. Pagination is page-based with up to 1000 pages. Omitting all filters returns the full marketplace feed.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `available_for_credit` | string | No | Filter for credit-eligible listings. |
| `body` | string | No | Body type filter. |
| `color` | string | No | Color filter. |
| `customs` | string | No | Customs cleared status filter. |
| `drive` | string | No | Drive type filter. |
| `engine_volume_from` | string | No | Minimum engine volume in liters. |
| `engine_volume_to` | string | No | Maximum engine volume in liters. |
| `generation` | string | No | Generation slug filter. |
| `is_broken` | string | No | Filter for broken/not running vehicles. |
| `mark` | string | No | Car make slug from get_makes urlAlias (e.g. 'toyota', 'hyundai', 'bmw'). |
| `mileage_to` | string | No | Maximum mileage filter. |
| `model` | string | No | Car model slug from get_models urlAlias (e.g. 'camry', 'land-cruiser-prado'). Requires mark to be set. |
| `page` | integer | No | Page number for pagination. |
| `price_from` | string | No | Minimum price in KZT (e.g. '5000000'). |
| `price_to` | string | No | Maximum price in KZT (e.g. '15000000'). |
| `region` | string | No | Region/city slug from get_cities alias (e.g. 'almaty', 'region-almatinskaya-oblast'). |
| `steering_wheel` | string | No | Steering wheel position filter. |
| `transmission` | string | No | Transmission type filter. |
| `with_history` | string | No | Filter for listings with history report. |
| `with_photo` | string | No | Filter for listings with photos only. |
| `year_from` | string | No | Minimum production year (e.g. '2018'). |
| `year_to` | string | No | Maximum production year (e.g. '2024'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/search_cars \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"available_for_credit":"<string>","body":"<string>","color":"<string>","customs":"<string>","drive":"<string>","engine_volume_from":"<string>","engine_volume_to":"<string>","generation":"<string>","is_broken":"<string>","mark":"<string>","mileage_to":"<string>","model":"<string>","page":"<integer>","price_from":"<string>","price_to":"<string>","region":"<string>","steering_wheel":"<string>","transmission":"<string>","with_history":"<string>","with_photo":"<string>","year_from":"<string>","year_to":"<string>"}'
```

### search_other_categories

Search listings in non-car vehicle categories: commercial vehicles (trucks, buses, special equipment), motorcycles, or water transport. Returns paginated summaries in the same shape as search_cars. The category parameter is required and closed to three values.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `category` | string | Yes | Vehicle category to search. Accepted values: 'commercial', 'motorcycles', 'water'. |
| `page` | integer | No | Page number for pagination. |
| `region` | string | No | Region/city slug (e.g. 'almaty'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/search_other_categories \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"category":"<string>","page":"<integer>","region":"<string>"}'
```

### search_spare_parts

Search spare parts listings on Kolesa.kz. The site is Russian-language, so queries in Russian or Kazakh yield the best results (e.g. 'фара' for headlight, 'двигатель' for engine). Supports filtering by make, model, and region. Paginated up to 1000 pages.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `mark` | string | No | Car make slug (e.g. 'toyota', 'bmw'). |
| `model` | string | No | Car model slug (e.g. 'camry', 'corolla'). |
| `page` | integer | No | Page number for pagination. |
| `query` | string | No | Search text query in Russian or Kazakh (e.g. 'фара', 'двигатель', 'тормозные колодки'). |
| `region` | string | No | Region/city slug (e.g. 'almaty'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-kolesa-kz-api-4a328b2b/search_spare_parts \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mark":"<string>","model":"<string>","page":"<integer>","query":"<string>","region":"<string>"}'
```