# Allegro API scraper — search Poland's #1 marketplace (allegro.pl): listings with price, condition, delivery & category filters, offer/product detail, category browse, related offers and a seller's full catalogue. Prices in PLN, results paginated.

> Search Allegro by keyword — returns offer cards with title, price (PLN), delivery cost, seller, rating, photos and offer URL. Supports price range, condition, free-delivery, sort and category filters, with page pagination.
> ReefAPI engine `allegro` · 5 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/allegro/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed or blocked calls are free.
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /allegro/v1/search — 2 credits
Search Allegro by keyword — returns offer cards with title, price (PLN), delivery cost, seller, rating, photos and offer URL. Supports price range, condition, free-delivery, sort and category filters, with page pagination.

**Parameters:**
- `query` (string, required) — What to search for (offer keywords, Polish or any language).
- `max_pages` (integer, optional, default 1) — How many result pages to fetch (1–10). Each page ≈ 60 offers.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, price_asc, price_desc, popularity, newest]
- `min_price` (number, optional) — Minimum price filter, in PLN.
- `max_price` (number, optional) — Maximum price filter, in PLN.
- `condition` (enum, optional) — Item condition filter. [one of: new, used]
- `free_delivery` (boolean, optional) — Only offers with free delivery (darmowa dostawa).
- `category` (string, optional) — Restrict to an Allegro category slug (the slug in a category URL, e.g. telefony-komorkowe-165).

**Returns:** offers[]{id, title, url, price{amount,currency}, delivery_text, seller{login, super_seller, positive_feedback_percent}, rating, rating_count, images[], parameters[]} + total, last_page, pages_fetched

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

### POST /allegro/v1/category — 2 credits
Browse an Allegro category without a keyword (the /kategoria/<slug> grid) — discover popular offers in a category. Supports price/condition/free-delivery/sort filters and page pagination.

**Parameters:**
- `category` (enum, required) — Allegro category to browse — a top-level slug below, or any category slug from a category URL (e.g. telefony-komorkowe-165). [one of: elektronika, moda, dom-i-ogrod, dziecko, kultura-i-rozrywka, motoryzacja, sport-i-turystyka, zdrowie, uroda, supermarket]
- `max_pages` (integer, optional, default 1) — How many category pages to fetch (1–10).
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, price_asc, price_desc, popularity, newest]
- `min_price` (number, optional) — Minimum price filter, in PLN.
- `max_price` (number, optional) — Maximum price filter, in PLN.
- `condition` (enum, optional) — Item condition filter. [one of: new, used]
- `free_delivery` (boolean, optional) — Only offers with free delivery.

**Returns:** offers[] (same shape as search) + category_path, total, last_page, pages_fetched

### POST /allegro/v1/offer — 2 credits
Single Allegro offer/product detail by id or URL — title, price (PLN), main image and gallery, seller handle, and description.

**Parameters:**
- `offer_id` (string, optional) — Allegro offer id — the digits in an offer URL (allegro.pl/oferta/<id>). Provide offer_id OR offer_url.
- `offer_url` (string, optional) — Full offer/product URL — alternative to offer_id.

**Returns:** offer{id, url, title, price{amount,currency}, price_string, image_url, images[], seller{login, listing_url}, description}

### POST /allegro/v1/seller_offers — 2 credits
A seller's public active listings, paginated — every offer a seller (shop) has live. Provide the seller login (handle from a seller URL / a search result's seller.login).

**Parameters:**
- `seller` (string, required) — Allegro seller login/handle (from allegro.pl/uzytkownik/<login> or a search result's seller.login).
- `max_pages` (integer, optional, default 1) — How many of the seller's listing pages to fetch (1–10).
- `sort` (enum, optional, default "relevance") — Order within the seller's listings. [one of: relevance, price_asc, price_desc, newest]

**Returns:** offers[] (same shape as search) + seller, total, last_page, pages_fetched

### POST /allegro/v1/suggested — 2 credits
Related/recommended Allegro offers for a keyword — a quick set of relevant offers (the first result page) useful for 'more like this' / market discovery.

**Parameters:**
- `query` (string, required) — Keyword to fetch related offers for.

**Returns:** offers[] (same shape as search) + total

**Example request body:**
```json
{
  "query": "iphone 15"
}
```

## More
- Try it live, no code: https://reefapi.com/playground?engine=allegro
- Human docs page: https://reefapi.com/docs/allegro
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt