{ "openapi": "3.0.0", "info": { "version": "1.0", "title": "4Sale Kuwait API", "description": "4Sale API for Kuwait classifieds data from Q84Sale (q84sale.com): used cars and cars for sale, property for rent and for sale, apartments, electronics, mobile phones, jobs and services listings with prices, sellers and districts. Kuwait classifieds API covering dealers and business profiles, a business directory of restaurants, cafés, clinics and salons, and new car prices in KWD, in English and Arabic. Build Kuwait classifieds apps similar to OpenSooq, Dubizzle, Haraj, Motory and Carsemsar.", "x-category": "Data", "x-long-description": "# 🇰🇼 4Sale API\n\nBring Kuwait classifieds data from 4Sale (q84sale.com) into your application: search and browse used cars, property for rent and for sale, electronics, mobile phones, services, jobs and furniture listings with prices in KWD, open any listing in full with its seller, quality score and view history, follow dealers and business profiles to their whole inventory, explore the business directory of restaurants, cafés, clinics and salons, and look up new car prices, in English and Arabic.\n\n| Feature | Details |\n| --- | --- |\n| **Last Updated** | **October 9, 2026** |\n| 🇰🇼 **Kuwait Market Coverage** | All six governorates (Kuwait City, Hawalli, Farwaniyah, Ahmadi, Jahra and Mubarak Al-Kabeer) with their areas and blocks; every listing carries its district path from Kuwait down to the block |\n| 🗂️ **Categories Carried** | Cars and other vehicles, property for rent and for sale, electronics and mobile phones, services, jobs, furniture and the rest of the 4Sale category tree, with each category's attribute dictionary |\n| 🔍 **Search Filters** | `searchListings`: 11 parameters, including keyword, price range in KWD, attribute filters such as year, mileage and rooms (up to 12 clauses), video only, photos only, a map point and 4 sort orders. `listCategoryListings`: 10 parameters, including extra categories, up to 30 districts, service area, price range, attribute filters and 5 sort orders |\n| 🔗 **URL Front Doors** | Paste a q84sale.com category page address and get its listings with the site's own filters applied, or paste a listing page address and get the full listing record |\n| 📈 **Listing Score and Views** | The marketplace's quality score broken down by factor with improvement advice, day by day and hour by hour view history, and phone, WhatsApp and chat contact clicks |\n| 🏢 **Dealers and Business Profiles** | Car dealers, car and property offices, electronics shops and service companies with contact numbers, verification and branches, plus each business's full listing inventory with an exact total |\n| 🍽️ **Business Directory** | Restaurants, cafés, clinics, salons, gyms and other local businesses with phone numbers, websites, opening hours, amenities, branches with coordinates, star ratings, user reviews, photos and menus |\n| 🚗 **New Car Catalogue** | New models by brand with body style, engine and fuel types, every trim and its price in KWD |\n| 📣 **Paid Placements and Promotions** | A category's pinned, rotating, business, commercial and golden listings, sponsored cards, home screen banners and promo codes |\n| 🌐 **English and Arabic** | Titles, descriptions, category names, district names and business names in both languages; Arabic search with spelling-variant matching |\n| ⚡ API Type | Fast REST API via RapidAPI |\n\n## Overview\n\nThe 4Sale API is an unofficial Kuwait classifieds API for 4Sale (q84sale.com). It is not affiliated with 4Sale. Search the marketplace by keyword or browse any category with the filters buyers use on the site, open listings with decoded attributes, coordinates and seller details, and measure how a listing performs. Follow a seller or dealer to everything they have listed, and reach the business directory, the new-car catalogue and the local service offers from the same integration.\n\nIt is built for car and property portals, price comparison and market research tools, dealer and lead generation products, local business guides and data teams that need Kuwait classifieds data in their own products.\n\n## Key Features\n\n- Search every category by keyword in English or Arabic, or search inside one category with district, price and attribute filters.\n- Browse a category, or several at once, by district, price range and attributes such as year, mileage, rooms and pool.\n- Walk Kuwait's governorates, areas and blocks, and find a district or category by its English or Arabic name.\n- Paste q84sale.com category and listing page addresses instead of building filters or extracting IDs.\n- Open a listing's full bilingual record with decoded attributes, coordinates, seller phone and promotion state.\n- See a listing's quality score, its daily and hourly view history and its contact clicks.\n- Follow the latest listings across the whole catalogue as one newest-first feed.\n- List a seller's active listings by phone number, and a business profile's whole inventory by slug.\n- Search the business directory and open each business's details, reviews, photos and menus.\n- Look up new car models, trims and prices in KWD.\n- See what the marketplace promotes: paid placements, sponsored cards, home screen banners and promo codes.\n\n## Available Data\n\nListing IDs, slugs and page addresses; titles and descriptions in English and Arabic; prices in KWD, with \"price on request\" listings marked; categories with names in both languages and full breadcrumbs; decoded attributes such as make, model, year, mileage, rooms and area, with their units; district names and paths from governorate to block; map coordinates where the seller pinned a point; images, video and photo counts; posting and bump dates; premium, pinned and paid placement flags; seller phone numbers, account type, verification and business profile links; view counts.\n\nListing performance data covers the overall quality score and its factors with advice, daily and hourly views and contact clicks by type. Business profiles carry names in both languages, logos, contact numbers, verification, membership date and branches. Directory businesses carry categories, tags, phone numbers, websites, opening hours, amenities, price range, branches with coordinates, star ratings with their breakdown, user reviews, photos and menus. The new-car catalogue carries brands, models, model years, body styles, engines, fuel types, trims and prices in KWD. Marketplace data covers sponsored cards, home screen sections and banners, promo codes, local service offers with phone and WhatsApp numbers, trending searches and featured blog articles.\n\n## Categories & Locations\n\n### `listCategories` (`/categories`)\n\nBrowse the 4Sale category tree from the top-level verticals down, or find a category by its English or Arabic name. Use it to get the category IDs that browsing, category search, business profiles and sponsored cards take.\n\n### `getCategoryDetails` (`/category-details`)\n\nGet one category's bilingual description, breadcrumb and direct children. Use it to build category pages and navigation.\n\n### `getCategoryFilters` (`/category-filters`)\n\nGet a category's attribute dictionary: every attribute with its type, unit and options in English and Arabic. Use it to build filter panels and to find the attribute and option IDs the `attributes` filter takes.\n\n### `listDistricts` (`/districts`)\n\nList Kuwait's six governorates, then their areas and blocks, or find a district by its English or Arabic name. Use it to get the district IDs that the district filters take.\n\n### `getSearchSuggestions` (`/autocomplete`)\n\nTurn a phrase the user is typing into search suggestions in English or Arabic, together with the category to browse. Use it for search boxes and to jump from a typed model name to its category.\n\n### `listTrendingSearches` (`/trending-searches`)\n\nGet the search phrases trending on the marketplace right now. Use it for trending tags and demand signals.\n\n## Search\n\n### `searchListings` (`/search`)\n\nSearch every category by keyword in English or Arabic, with price range, attribute, video, photo and near-a-point filters and four sort orders, up to 100 listings per page. Use it when you do not know the category. Listing cards carry a short description of up to 200 characters; the full text is on `getListingDetails`.\n\n### `listCategoryListings` (`/listings`)\n\nBrowse one category, optionally together with others, filtered by districts, service area, price range and attributes, in five sort orders. Use it for category pages, inventory sweeps and price research. In the default order a category's pinned paid listings are not part of this list; they are on `listPromotedListings`.\n\n### `searchCategoryListings` (`/category-search`)\n\nSearch by keyword inside one category and everything beneath it, with district, price range and attribute filters. Matching is typo-tolerant, so a trim name such as TXL also finds its spelling variants.\n\n### `listLatestListings` (`/latest-listings`)\n\nFollow the whole live catalogue as one roughly newest-first feed, 30 listings per page, optionally narrowed to a piece of text. Use it to catch new listings or to sync the catalogue in bulk.\n\n### `listListingsByUrl` (`/listings-by-url`)\n\nPaste a q84sale.com category page address, with the filters the site keeps in it, and get the same listings back together with how the address was understood. Use it when your users start from a 4Sale page.\n\n### `listPromotedListings` (`/promoted-listings`)\n\nGet a category's paid placements: its pinned, rotating, business, commercial and golden listings, optionally narrowed by district or service area. Use it to track who pays for visibility in a category.\n\n### `listPopularListings` (`/popular-listings`)\n\nGet the most viewed listings right now in each major vertical. Use it for \"popular now\" rails and demand tracking.\n\n## Listings\n\n### `getListingDetails` (`/listing-details`)\n\nOpen one listing by ID: full bilingual title and description, price, decoded attributes, district path, coordinates, images and video, seller details and promotion state. Each call adds one view to the listing's public view count on 4Sale, so use `getListingScore`, `getListingViews` or `listSimilarListings` when you only need those.\n\n### `getListingDetailsByUrl` (`/listing-details-by-url`)\n\nPaste a q84sale.com listing page address, English or Arabic, and get the same full record `getListingDetails` returns. Like `getListingDetails`, each call adds one view on 4Sale.\n\n### `getListingScore` (`/listing-score`)\n\nGet the marketplace's quality score for a listing, broken down by factor (title, description, images, readability and word variety) with explanations and improvement advice in English and Arabic. Use it to audit listing quality or rank a seller's inventory. It adds no view.\n\n### `getListingViews` (`/listing-views`)\n\nGet a listing's view history day by day and hour by hour since it was published, and how often buyers used its phone, WhatsApp and chat buttons. Use it to measure listing performance and demand. It adds no view.\n\n### `listSimilarListings` (`/similar-listings`)\n\nGet the listings the marketplace recommends alongside one listing, usually from the same category. Use it for comparables, alternatives and \"you may also like\" rails.\n\n## Sellers\n\n### `listSellerListings` (`/seller-listings`)\n\nList the active listings of one seller account by its phone number, with its paid pinned listings shown separately. Use it to size a seller, collect a shop's stock or spot a dealer posting as a private seller.\n\n### `listBusinessProfiles` (`/business-profiles`)\n\nFind the dealers, offices and service companies on the marketplace, either by the categories they have listings in or by business directory (car offices, property offices, dealerships, electronics shops and car garages). Use it to build dealer lists and lead lists.\n\n### `getBusinessProfileDetails` (`/business-profile-details`)\n\nOpen one business profile by slug: names in English and Arabic, logo, about text, membership date, contact numbers, verification and branches.\n\n### `listBusinessProfileListings` (`/business-profile-listings`)\n\nPage through a business profile's full inventory with an exact total. Use it to track a dealer's stock and prices.\n\n### `searchDirectoryBusinesses` (`/directory-search`)\n\nSearch the business directory of restaurants, cafés, clinics, salons and other local businesses by name or kind, in English or Arabic, filtered by directory category and tags and sorted by relevance, rating or newest. Results include opening hours and tags.\n\n### `getDirectoryBusinessDetails` (`/directory-business-details`)\n\nOpen one directory business by slug: phone numbers, website, amenities, opening hours, branches with coordinates, star rating with its breakdown and page view count, in English or Arabic.\n\n### `listDirectoryBusinessReviews` (`/directory-business-reviews`)\n\nPage through the user reviews of one directory business, newest first. Use it for review widgets and reputation tracking.\n\n### `listDirectoryBusinessMedia` (`/directory-business-media`)\n\nGet the photos and menus of one directory business. Use it for business pages and menu galleries.\n\n## Marketplace\n\n### `listSponsoredCards` (`/sponsored-cards`)\n\nGet the sponsored banner cards shown in a category's search results. Use it to monitor advertisers by category.\n\n### `listPromoCodes` (`/promo-codes`)\n\nGet the promo codes currently valid for posting ads on the marketplace.\n\n### `getHomeSections` (`/home-sections`)\n\nGet what the home screen is promoting: trending categories, hero banners and sponsored cards, in English or Arabic.\n\n### `searchNewCars` (`/new-cars`)\n\nSearch the new-car catalogue by brand, model or trim name in English and get each model with its body style, engine, fuel types, every trim and its price in KWD where the dealer publishes one. Use it to answer \"what does a new Prado cost?\" or to list every new Toyota.\n\n### `listServiceOffers` (`/service-offers`)\n\nGet the local service businesses advertising on the marketplace, such as AC repair, movers and car rental, with phone and WhatsApp numbers, in English or Arabic. Filter by service category.\n\n### `listServiceCategories` (`/service-categories`)\n\nList the service categories and the IDs that `listServiceOffers` filters by.\n\n### `listBlogArticles` (`/blog-articles`)\n\nGet the editorial blog posts the marketplace's app features, with titles, summaries and links, in English or Arabic.\n\n## Plan Access\n\nEvery endpoint in the table is free to try on Basic. Pro includes category and location lookup, listing search and browse, and full listing details. Ultra adds listing score and view history, dealers and business profiles, and the new-car and service catalogues. Mega includes every endpoint, including the local business directory and paid placement and promotion data. Basic is a trial of the whole API, so Pro and Ultra do not include every endpoint Basic can try; if you need every endpoint, choose Mega. A green tick means the endpoints in that row are available on the plan; a red cross means they are not.\n\n| Feature | Endpoints | Basic | Pro | Ultra | Mega |\n| --- | --- | :---: | :---: | :---: | :---: |\n| 🗂️ Categories and Locations Lookup | `listCategories`, `getCategoryDetails`, `getCategoryFilters`, `listDistricts`, `getSearchSuggestions`, `listTrendingSearches` | ✓ | ✓ | ✓ | ✓ |\n| 🔍 Classifieds Listing Search | `searchListings`, `listCategoryListings`, `searchCategoryListings`, `listLatestListings`, `listListingsByUrl`, `listPopularListings` | ✓ | ✓ | ✓ | ✓ |\n| 📄 Full Listing Details | `getListingDetails`, `getListingDetailsByUrl` | ✓ | ✓ | ✓ | ✓ |\n| 📈 Listing Performance Insights | `getListingScore`, `getListingViews`, `listSimilarListings` | ✓ | ✗ | ✓ | ✓ |\n| 🏢 Dealer and Business Profiles | `listSellerListings`, `listBusinessProfiles`, `getBusinessProfileDetails`, `listBusinessProfileListings` | ✓ | ✗ | ✓ | ✓ |\n| 🚗 New Cars and Services | `searchNewCars`, `listServiceOffers`, `listServiceCategories` | ✓ | ✗ | ✓ | ✓ |\n| 🍽️ Local Business Directory | `searchDirectoryBusinesses`, `getDirectoryBusinessDetails`, `listDirectoryBusinessReviews`, `listDirectoryBusinessMedia` | ✓ | ✗ | ✗ | ✓ |\n| 📣 Promotions and Featured Content | `listPromotedListings`, `listSponsoredCards`, `getHomeSections`, `listPromoCodes`, `listBlogArticles` | ✓ | ✗ | ✗ | ✓ |\n\n## Common Use Cases\n\n- Build Kuwait used car portals and car price comparison tools.\n- Build property search apps for apartments and other property for rent and for sale in Kuwait.\n- Research prices for cars, property, electronics and mobile phones by model, year, district and attributes.\n- Monitor new listings across the whole marketplace as they appear.\n- Track dealer and business inventory, prices and branches over time.\n- Generate leads from dealers, offices and local service companies.\n- Measure listing quality and performance with scores, view history and contact clicks.\n- Build local business guides with opening hours, ratings, reviews, photos and menus.\n- Show new car prices by brand, model and trim in KWD.\n- Track paid placements, sponsored cards and promotions by category.\n\n## Built for Developers\n\nEvery endpoint is a `GET` request with query parameters. Start with `listCategories`, `listDistricts`, `getCategoryFilters` or `getSearchSuggestions` to get valid category, district and attribute IDs, then search, browse and open the records your product needs. Successful responses carry `success: true` and `data`; failures carry `success: false` and a message that explains what to change.\n\nListing cards have one shape on every search, browse, seller and recommendation endpoint, so the same code handles them all. Each card's `listing_id` opens `getListingDetails`, `getListingScore`, `getListingViews` and `listSimilarListings`; its seller's phone opens `listSellerListings`, and a business profile slug opens `getBusinessProfileDetails` and `listBusinessProfileListings`. Paged endpoints report `total` and `total_pages`, and every request and response is documented with examples in the endpoint reference.\n\n## Why Use This API?\n\n- Cover the whole 4Sale marketplace with one integration: listings, sellers, dealers, the business directory and the new-car catalogue.\n- Filter like a 4Sale user: districts down to the block, price in KWD, and every filterable attribute of a category.\n- Go beyond listings with quality scores, view history and contact clicks.\n- Start from IDs, names or pasted q84sale.com addresses.\n- Work in English and Arabic, with Arabic search that matches spelling variants.\n\n## API Categories\n\n- Categories & Locations\n- Search\n- Listings\n- Sellers\n- Marketplace\n\n## Start Building\n\nFind a category or district, search or browse Kuwait classifieds with the filters your users need, and open the listing, seller, business and new-car data your product requires. Start on Basic to try every endpoint, then choose Pro, Ultra or Mega according to the endpoints your production workflow needs.", "x-website": "https://www.q84sale.com", "x-public": true, "x-thumbnail": "https://rapidapi-prod-apis.s3.amazonaws.com/c8a34954-1471-40be-af67-1943f43e7ef8.png", "x-version-lifecycle": "active", "termsOfService": "Unofficial 4Sale (q84sale.com) Kuwait classifieds data API; not affiliated with 4Sale." }, "tags": [ { "name": "Categories & Locations", "description": "Categories & Locations", "index": 0 }, { "name": "Search", "description": "Search", "index": 1 }, { "name": "Listings", "description": "Listings", "index": 2 }, { "name": "Sellers", "description": "Sellers", "index": 3 }, { "name": "Marketplace", "description": "Marketplace", "index": 4 }, { "name": "Health", "description": "Health", "index": 5 } ], "components": { "schemas": { "CommonHealthCheckResponse": { "type": "object", "properties": { "success": { "type": "boolean", "example": true } }, "required": [ "success" ] }, "FourSaleSuccessResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ true ], "example": true }, "data": { "nullable": true } }, "required": [ "success" ] }, "FourSaleErrorResponseSchema": { "type": "object", "properties": { "success": { "type": "boolean", "enum": [ false ], "example": false }, "message": { "type": "string", "example": "An unexpected error occurred. Please try again." } }, "required": [ "success", "message" ] } }, "parameters": {} }, "paths": { "/status": { "get": { "tags": [ "Health" ], "operationId": "getServiceStatus", "description": "Check whether the 4Sale API is available.", "responses": { "200": { "description": "Health check", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommonHealthCheckResponse" } } } } } } }, "/categories": { "get": { "tags": [ "Categories & Locations" ], "operationId": "listCategories", "description": "Browse or search the category tree to find the category ids /listings, /listings-by-url, /category-search, /category-details, /category-filters, /sponsored-cards and /business-profiles take.", "parameters": [ { "schema": { "type": "integer", "description": "**Return the direct children of this category.** Optional. A numeric category id; omit it (and\n`query`) for the top-level verticals (Automotive, Property, Electronics, Services, …).\n\n- Walk the tree downward by passing any returned `category_id` back as `parent_id`.\n- The `parent` object in the response echoes the node you asked for with its full `path`.\n- An unknown id returns **404**; accepts 1–999,999,999.", "minimum": 1, "maximum": 999999999 }, "required": false, "description": "**Return the direct children of this category.** Optional. A numeric category id; omit it (and\n`query`) for the top-level verticals (Automotive, Property, Electronics, Services, …).\n\n- Walk the tree downward by passing any returned `category_id` back as `parent_id`.\n- The `parent` object in the response echoes the node you asked for with its full `path`.\n- An unknown id returns **404**; accepts 1–999,999,999.", "name": "parent_id", "in": "query" }, { "schema": { "type": "string", "description": "**Find categories by name instead of walking the tree.** Optional. Case-insensitive text matched\nagainst the English name, the Arabic name and the slug of every category, e.g. `land cruiser`,\n`apartment`, `شقة`.\n\n- Arabic spelling variants match each other (`ايجار` finds `إيجار`, `شقه` finds `شقة`).\n- Each match comes back with its full `path` from the vertical down; `total` counts every match.\n- Takes precedence over `parent_id`. At most 100 matches are returned, shallowest first.", "maxLength": 100 }, "required": false, "description": "**Find categories by name instead of walking the tree.** Optional. Case-insensitive text matched\nagainst the English name, the Arabic name and the slug of every category, e.g. `land cruiser`,\n`apartment`, `شقة`.\n\n- Arabic spelling variants match each other (`ايجار` finds `إيجار`, `شقه` finds `شقة`).\n- Each match comes back with its full `path` from the vertical down; `total` counts every match.\n- Takes precedence over `parent_id`. At most 100 matches are returned, shallowest first.", "name": "query", "in": "query" } ], "responses": { "200": { "description": "**The category tree — the category ids /listings, /category-search, /category-filters,\n/business-profiles and the other listing-category endpoints take.** Three modes:\n\n- **no parameters** — the top-level verticals;\n- **`parent_id`** — the direct children of one category, with the parent echoed back;\n- **`query`** — a name search across the whole tree (English, Arabic or slug), each match with its path.\n\nEvery node carries `category_id`, `parent_id`, `name_en`, `name_ar`, `slug`, `category_type`,\n`has_listings`, `children_count`, `depth`, `image`, `feature_image` (`null` where the category has no\npicture), `posting_allowed` (whether sellers can post directly in it), `posting_fee` (the base fee in\nKWD to post an ad in that category), `video_allowed` (whether an ad posted there may carry a video,\nfrom the category's posting rules) and `display_order`. Every category can\nbe filtered by where its listings are located (`district_ids` on /listings); the service categories\n(`category_type: listings_district_filteration` — plumbers, electricians, movers, cleaning, …) can also\nbe filtered by the governorate a provider serves (`service_area_id` on /listings).\n\n**`has_listings` tells you where to browse.** A node whose `category_type` is `sub_categories` is a\nnavigation group (`has_listings: false`) — /listings refuses it with a 400 naming its children. Every\nother node holds listings, and a non-leaf node returns its **whole subtree**: browsing `138` (Toyota)\nincludes every Land Cruiser, Prado and Camry beneath it.\n\nNext calls: /listings?category_id= to browse, /category-filters?category_id= for the attributes it is\nfiltered by, /category-details?category_id= for its description and breadcrumb.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": null, "parent": null, "total": 14, "categories": [ { "category_id": 1540, "parent_id": null, "name_en": "Automotive", "name_ar": "محركات", "slug": "automotive", "category_type": "sub_categories", "has_listings": false, "children_count": 18, "image": "https://static.q84sale.com/images/cat_image/base_TdhUKinyJ0cT.png", "feature_image": "https://static.q84sale.com/images/cat_image/xnOaO6tbYIhd@6x.png", "posting_allowed": true, "posting_fee": 3, "video_allowed": true, "display_order": 10, "depth": 0 }, { "category_id": 89, "parent_id": null, "name_en": "Property", "name_ar": "عقارات", "slug": "property", "category_type": "sub_categories", "has_listings": false, "children_count": 7, "image": "https://static.q84sale.com/images/cat_image/image_1_1_89.png", "feature_image": "https://static.q84sale.com/images/cat_image/image_16_9_89.png", "posting_allowed": true, "posting_fee": 4.5, "video_allowed": true, "display_order": 20, "depth": 0 } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/category-details": { "get": { "tags": [ "Categories & Locations" ], "operationId": "getCategoryDetails", "description": "One category's bilingual description, breadcrumb and direct children.", "parameters": [ { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.", "example": 138, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.", "name": "category_id", "in": "query" } ], "responses": { "200": { "description": "**One category in full: its bilingual description, breadcrumb and direct children.** Use it to label a\ncategory page, to show where a category sits in the tree, or to list what is beneath it.\n\nReturns everything /categories gives for a node (`name_en`, `name_ar`, `slug`, `category_type`,\n`has_listings`, `posting_fee`, …) plus:\n\n- `description_en` / `description_ar` — the category's own marketing description, both languages\n (`null` where it has none);\n- `breadcrumbs` — the path from the top-level vertical down to this category, both languages;\n- `children` — the direct children, each with its own `children_count`: the same rows\n /categories?parent_id= returns;\n- `is_leaf`, `depth` and `has_plans` (paid posting plans exist for it);\n- `pinning_shuffle_factor` / `commercial_pinning_shuffle_factor` — 4Sale's rotation factors for pinned\n and commercial placements in the category, as served.\n\nAn unknown id is a **404**. If part of the record cannot be read the rest is still returned and\n`partial_errors` names the missing part: `seo_copy` (the descriptions can then be `null`, and both\nrotation factors are `null`) or `breadcrumbs` (the breadcrumb is then built from the category tree). An\nempty `partial_errors` means complete.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category_id": 138, "parent_id": 2897, "name_en": "Toyota", "name_ar": "تويوتا", "slug": "toyota", "category_type": "listings", "has_listings": true, "children_count": 41, "image": "https://static.q84sale.com/images/cat_image/apr_138.png", "feature_image": "https://static.q84sale.com/images/cat_image/newappicon_138.png", "posting_allowed": true, "posting_fee": 6, "video_allowed": true, "display_order": 5, "depth": 2, "is_leaf": false, "description_en": "Be a proud owner of the Kuwaitis’ favorite car on the road and find the right Toyota car for sale on our platform. Visit 4Sale now and start browsing.", "description_ar": "احصل على السيارة المفضلة لدى الكويتيين على الطريق واعثر على سيارة تويوتا المناسبة للبيع على منصتنا. قم بزيارة 4Sale الآن وابدأ التصفح.", "pinning_shuffle_factor": 3, "commercial_pinning_shuffle_factor": 2, "has_plans": true, "breadcrumbs": [ { "category_id": 1540, "slug": "automotive", "name_en": "Automotive", "name_ar": "محركات" }, { "category_id": 2897, "slug": "used-cars", "name_en": "Used Cars", "name_ar": "سيارات مستعملة" }, { "category_id": 138, "slug": "toyota", "name_en": "Toyota", "name_ar": "تويوتا" } ], "children": [ { "category_id": 5466, "parent_id": 138, "name_en": "Highlander", "name_ar": "هايلاندر", "slug": "highlander-2", "category_type": "listings", "has_listings": true, "children_count": 0, "image": "https://static.q84sale.com/images/cat_image/apr_138.png", "feature_image": "https://static.q84sale.com/images/cat_image/newappicon_138.png", "posting_allowed": true, "posting_fee": 6, "video_allowed": true, "display_order": 0, "depth": 3 }, { "category_id": 1983, "parent_id": 138, "name_en": "Land Cruiser", "name_ar": "لاند كروزر", "slug": "land-cruiser", "category_type": "listings", "has_listings": true, "children_count": 0, "image": "https://static.q84sale.com/images/cat_image/apr_138.png", "feature_image": "https://static.q84sale.com/images/cat_image/newappicon_138.png", "posting_allowed": true, "posting_fee": 6, "video_allowed": true, "display_order": 0, "depth": 3 } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/category-filters": { "get": { "tags": [ "Categories & Locations" ], "operationId": "getCategoryFilters", "description": "A category's attribute dictionary — the ids and option ids the `attributes` filter takes and listing attributes decode against.", "parameters": [ { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- Attributes are inherited: a model such as `1971` (Prado) returns the attributes of Used Cars.", "example": 2888, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- Attributes are inherited: a model such as `1971` (Prado) returns the attributes of Used Cars.", "name": "category_id", "in": "query" }, { "schema": { "type": "boolean", "description": "**Return only the attributes the marketplace app shows in its filter panel** (`filterable: true`).\nOptional; send `true` or `false`.\n\n- Omitted or `false`: every attribute, so a listing's `attributes` can always be decoded.\n- The flag is about the app's panel only: every drop-down, number and yes/no attribute recorded on\n listings can be used in `attributes=` on /search and /listings, `filterable: false` ones included\n (`text`, `file` and `multi_selection` attributes cannot, whatever the flag says).", "example": "" }, "required": false, "description": "**Return only the attributes the marketplace app shows in its filter panel** (`filterable: true`).\nOptional; send `true` or `false`.\n\n- Omitted or `false`: every attribute, so a listing's `attributes` can always be decoded.\n- The flag is about the app's panel only: every drop-down, number and yes/no attribute recorded on\n listings can be used in `attributes=` on /search and /listings, `filterable: false` ones included\n (`text`, `file` and `multi_selection` attributes cannot, whatever the flag says).", "name": "filterable_only", "in": "query" } ], "responses": { "200": { "description": "**The attribute dictionary of a category — what its listings are described and filtered by.** Use it to\nbuild the `attributes` filter of /search and /listings, and to decode the raw `{attribute_id, value}`\npairs every listing card carries.\n\nEach attribute has `attribute_id`, `name_en`, `name_ar`, `type` and, depending on the type:\n\n- `drop_down` — `options[]` of `{option_id, label_en, label_ar, icon}`; filter with\n `:` or several ids joined by `|` (any of them);\n- `number` — `unit_en`/`unit_ar` and, where the category bounds it, `min`/`max`; filter with a range\n `:-` or an exact number;\n- `bool` — a yes/no feature; filter with `:1` (the seller ticked it) — `:0`\n matches only listings whose seller explicitly answered \"no\";\n- `price_duration_drop_down` — the period a rental price is quoted for (`250` Price Duration: Monthly,\n Weekly, Daily), with `options[]` like a drop-down;\n- `multi_selection` — a picker such as `277` Color; it is published with no options, so no filter can\n be built from it;\n- `text` — free text such as a plate number (`182`) or a job title (`229`), and `file` — an attachment\n such as a CV (`44`); these are shown on /listing-details but cannot be filtered on.\n\nEvery attribute also carries:\n\n- `selection` (`single`/`multi`) — how many values a listing may hold;\n- `filterable` — whether the marketplace app shows it in its filter panel, not whether `attributes=`\n accepts it (every drop-down, number and yes/no attribute recorded on listings can be filtered on);\n- `scope` (below), `required_on_post`, `unit_en`/`unit_ar`, `group_id`, `display_order`;\n- `icon` — `null` where the marketplace has only a placeholder;\n- `defined_on_category_id` — the ancestor the attribute is inherited from.\n\n**`scope`** says where a value lives: `listing` — entered by the seller on each listing (year,\nmileage, rooms); `category` — a spec-sheet field of the make or model (engine capacity, horsepower,\ntorque, trunk capacity on Used Cars). A `category`-scoped field is almost never recorded on a listing,\nso a filter on it usually matches nothing (`295` Horsepower, `304` Trunk Capacity); Brand Origin\n(`289`) is an exception that does filter.\n\nExample from Used Cars: `166` Year (drop-down, option `1056` = 2022), `57` Mileage (number, km), `188`\nTransmission (drop-down). An unknown category id is a **404**. A navigation-only group (`has_listings:\nfalse` on /categories) holds no listings: most return an empty list, but some (e.g. `808` Property For\nRent) return attributes of their own — for filtering, ask for the child category you will browse.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category": { "category_id": 2888, "name_en": "Apartment For Rent", "name_ar": "شقة للايجار", "slug": "apartment-for-rent", "path": [ { "category_id": 89, "slug": "property", "name_en": "Property", "name_ar": "عقارات" }, { "category_id": 808, "slug": "for-rent", "name_en": "Property For Rent", "name_ar": "عقار للإيجار" }, { "category_id": 2888, "slug": "apartment-for-rent", "name_en": "Apartment For Rent", "name_ar": "شقة للايجار" } ] }, "total": 21, "attributes": [ { "attribute_id": 45, "name_en": "Living room", "name_ar": "صالة", "type": "number", "selection": "multi", "filterable": true, "scope": "listing", "required_on_post": false, "unit_en": "Halls", "unit_ar": "صالات", "min": 0, "max": 10, "defined_on_category_id": 808, "group_id": 1, "display_order": 4, "icon": "https://static.q84sale.com/images/attributes_images/base_rX2wHQcDEQuV.png", "options": [] }, { "attribute_id": 46, "name_en": "Rooms", "name_ar": "الغرف", "type": "number", "selection": "multi", "filterable": true, "scope": "listing", "required_on_post": true, "unit_en": "Beds", "unit_ar": "غرف", "min": 1, "max": 10, "defined_on_category_id": 808, "group_id": 1, "display_order": 3, "icon": "https://static.q84sale.com/images/attributes_images/base_jrQRoczMaWM8.png", "options": [] } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/districts": { "get": { "tags": [ "Categories & Locations" ], "operationId": "listDistricts", "description": "Kuwait's governorates, areas and blocks — the ids the `district_ids` filter takes.", "parameters": [ { "schema": { "type": "integer", "description": "**Return the districts directly beneath this one.** Optional. A numeric district id; omitted, the six\ngovernorates (Kuwait City, Hawalli, Farwaniyah, Ahmadi, Jahra, Mubarak Al-Kabeer).\n\n- The hierarchy is governorate (`level` 1) → area (`level` 2, e.g. `54` Salmiya) → block (`level` 3).\n- Pass any returned id back as `parent_id` to go one level down; a block with nothing beneath it\n returns an empty list.\n- Some blocks list `level` 4 entries (named buildings or unit types, not places); asking for one, like\n an unknown id, is a **404**. Accepts 1–999,999,999.", "minimum": 1, "maximum": 999999999 }, "required": false, "description": "**Return the districts directly beneath this one.** Optional. A numeric district id; omitted, the six\ngovernorates (Kuwait City, Hawalli, Farwaniyah, Ahmadi, Jahra, Mubarak Al-Kabeer).\n\n- The hierarchy is governorate (`level` 1) → area (`level` 2, e.g. `54` Salmiya) → block (`level` 3).\n- Pass any returned id back as `parent_id` to go one level down; a block with nothing beneath it\n returns an empty list.\n- Some blocks list `level` 4 entries (named buildings or unit types, not places); asking for one, like\n an unknown id, is a **404**. Accepts 1–999,999,999.", "name": "parent_id", "in": "query" }, { "schema": { "type": "string", "description": "**Find a district by name.** Optional. Case-insensitive text matched against the English and Arabic\nnames of every governorate, area and block, e.g. `salmiya`, `jabriya`, `السالمية`.\n\n- Arabic spelling variants match each other (`السالميه` finds `السالمية`, `الاحمدي` finds `الأحمدي`).\n- Takes precedence over `parent_id`; at most 200 matches are returned, `total` counts them all.\n- Search by area name: blocks are named `Block 1`…`Block 12` in every area, so a block search is\n ambiguous — find the area, then list its blocks with `parent_id`.", "maxLength": 100 }, "required": false, "description": "**Find a district by name.** Optional. Case-insensitive text matched against the English and Arabic\nnames of every governorate, area and block, e.g. `salmiya`, `jabriya`, `السالمية`.\n\n- Arabic spelling variants match each other (`السالميه` finds `السالمية`, `الاحمدي` finds `الأحمدي`).\n- Takes precedence over `parent_id`; at most 200 matches are returned, `total` counts them all.\n- Search by area name: blocks are named `Block 1`…`Block 12` in every area, so a block search is\n ambiguous — find the area, then list its blocks with `parent_id`.", "name": "query", "in": "query" } ], "responses": { "200": { "description": "**Kuwait's district gazetteer — the ids the `district_ids` filter of /listings takes.** Three modes:\n\n- **no parameters** — the six governorates;\n- **`parent_id`** — the areas of a governorate, or the blocks of an area, with `level` and `parent_id`;\n- **`query`** — a name search over every district (English or Arabic). Search results carry\n `district_id`, `name_en` and `name_ar`; `level` and `parent_id` are `null` in this mode — drill down\n with `parent_id` when you need the hierarchy.\n\nEvery entry also carries `attributes` (`[{attribute_id, value}]`). It is populated only on `level` 4\nentries and empty on every governorate, area and block. `images` is the entry's media list as served\n(usually empty).\n\n- **`level` 4 entries are not listing locations:** they are named buildings or unit types beneath some\n blocks (e.g. under Salmiya Block 1), and many carry the unit's property attributes — rooms, area,\n pool, … as raw ids and values (numbers, or `true`/`false` for a feature).\n- Decode the ids with /category-filters?category_id=2888 (e.g. `46` rooms, `66` area in m², `45` living\n rooms, `55` bathrooms, `65` pool).\n- Filter /listings by the block, not by these entries.\n\nA district filter includes everything beneath it, so filtering /listings by a governorate id covers all\nof its areas and blocks. Every listing also reports its own district (`district` on cards, a full\n`district_path_en`/`district_path_ar` on /listing-details).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": null, "parent_id": 1, "total": 6, "districts": [ { "district_id": 2, "name_en": "Ahmadi", "name_ar": "الأحمدي", "level": 1, "parent_id": 1, "attributes": [], "images": [] }, { "district_id": 3, "name_en": "Jahra", "name_ar": "الجهراء", "level": 1, "parent_id": 1, "attributes": [], "images": [] } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/autocomplete": { "get": { "tags": [ "Categories & Locations" ], "operationId": "getSearchSuggestions", "description": "Turn a typed phrase into search suggestions and the category id to browse.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 100, "description": "**What the user has typed so far.** A partial or full phrase in English or Arabic, e.g. `toyota`,\n`iphone 15`, `شقة`. Required; 1–100 characters. HTML tags and script-like text are refused with 400.", "example": "toyota" }, "required": true, "description": "**What the user has typed so far.** A partial or full phrase in English or Arabic, e.g. `toyota`,\n`iphone 15`, `شقة`. Required; 1–100 characters. HTML tags and script-like text are refused with 400.", "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the suggestion labels.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\n`label` switches language (`Camry` vs `كامري`); `keyword` stays as the search phrase.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the suggestion labels.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\n`label` switches language (`Camry` vs `كامري`); `keyword` stays as the search phrase.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**Turn a typed phrase into search suggestions AND the category to browse.** The type-ahead behind the\nmarketplace's search box: each suggestion is a complete phrase plus the category it belongs to.\n\nEvery suggestion carries `keyword` (the phrase), `label` (its display name in `lang`) and up to three\ncategory ids, most general first:\n\n- `vertical_category_id` — the category the phrase's listings are filed under: `2897` Used Cars for\n `toyota`, but `2888` Apartments for Rent for `شقة`, `130` Dogs for `dog`, `181` for `ps5`;\n- `category_id` — a make or brand, when the phrase names one (e.g. `138` Toyota);\n- `sub_category_id` — a model, when the phrase names one (e.g. `1971` Prado);\n- `browse_category_id` — the most specific of the three that /listings can browse, ready to pass\n straight to /listings?category_id=.\n\nAn id the marketplace has retired (no longer in the category tree) is `null`, so `browse_category_id`\nalways browses; it is `null` only when none of the three can be browsed.\n\nTypical flow: /autocomplete?query=toyota prado → `browse_category_id: 1971` → /listings?category_id=1971.\nOr take `keyword` to /search?query=. A phrase with no suggestions returns an empty list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": "toyota", "language": "en", "total": 6, "suggestions": [ { "keyword": "Toyota", "label": "Toyota", "vertical_category_id": 2897, "category_id": 138, "sub_category_id": null, "browse_category_id": 138 }, { "keyword": "Toyota corolla", "label": "Corola", "vertical_category_id": 2897, "category_id": 138, "sub_category_id": 1964, "browse_category_id": 1964 } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/trending-searches": { "get": { "tags": [ "Categories & Locations" ], "operationId": "listTrendingSearches", "description": "The search phrases trending on the marketplace right now.", "responses": { "200": { "description": "**What people are searching for on the marketplace right now.** The marketplace's own \"Trending\" list — a\ndemand signal, and a ready-made list of queries for /search.\n\nReturns `title_en`/`title_ar` (the list heading) and `terms[]`, each with:\n\n- `term` — the phrase as searched; pass it to /search. It is the Arabic phrase when there is one, so it\n usually equals `term_ar`.\n- `term_ar` — the Arabic phrase.\n- `term_en` — the English rendering, or `null` when the marketplace has no translation (common: most\n trending phrases are typed in Arabic).\n\nTakes no parameters; the list refreshes on the marketplace's own schedule.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "title_en": "Trending", "title_ar": "الأكثر بحثاً", "terms": [ { "term_en": null, "term_ar": "تفصال خيام", "term": "تفصال خيام" }, { "term_en": null, "term_ar": "اجهزة رياضية", "term": "اجهزة رياضية" } ] } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/search": { "get": { "tags": [ "Search" ], "operationId": "searchListings", "description": "Keyword search across every category, with price, attribute, video and near-a-point filters.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**The keyword search — what you would type in the marketplace search box.** Required; 1–200\ncharacters, English or Arabic, e.g. `prado`, `iphone 15 pro`, `شقة للايجار`.\n\n- Matches titles and descriptions across every category.\n- Matching is broad: a multi-word query is not an exact-phrase match, so `total` can be far larger\n than the listings containing the phrase. In relevance order the first pages hold the closest matches;\n narrow with a category (/category-search) or filters.\n- HTML tags, script-like text and a bare `0` are refused with 400.", "example": "prado" }, "required": true, "description": "**The keyword search — what you would type in the marketplace search box.** Required; 1–200\ncharacters, English or Arabic, e.g. `prado`, `iphone 15 pro`, `شقة للايجار`.\n\n- Matches titles and descriptions across every category.\n- Matching is broad: a multi-word query is not an exact-phrase match, so `total` can be far larger\n than the listings containing the phrase. In relevance order the first pages hold the closest matches;\n narrow with a category (/category-search) or filters.\n- HTML tags, script-like text and a bare `0` are refused with 400.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; omit it for relevance to `query`.\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n\nThe relevance order is not stable from one call to the next, so walking many pages in it can repeat\na few listings and skip others. To collect a complete result set, send a `sort` (e.g. `newest`).", "enum": [ "newest", "oldest", "price_low", "price_high" ] }, "required": false, "description": "**Result order.** Optional; omit it for relevance to `query`.\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n\nThe relevance order is not stable from one call to the next, so walking many pages in it can repeat\na few listings and skip others. To collect a complete result set, send a `sort` (e.g. `newest`).", "name": "sort", "in": "query" }, { "schema": { "type": "number", "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "name": "min_price", "in": "query" }, { "schema": { "type": "number", "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "name": "max_price", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only listings that include a video.** Optional. Send `true` to keep listings with a video tour;\nomitted or `false` applies no video restriction. How many listings carry a video differs a lot by\ncategory.", "example": "" }, "required": false, "description": "**Only listings that include a video.** Optional. Send `true` to keep listings with a video tour;\nomitted or `false` applies no video restriction. How many listings carry a video differs a lot by\ncategory.", "name": "video_only", "in": "query" }, { "schema": { "type": "boolean", "description": "**Only listings with at least one photo.** Optional. Send `true` to leave out listings posted without\na photo (including those that have only a video); omitted or `false` applies no photo restriction.", "example": "" }, "required": false, "description": "**Only listings with at least one photo.** Optional. Send `true` to leave out listings posted without\na photo (including those that have only a video); omitted or `false` applies no photo restriction.", "name": "images_only", "in": "query" }, { "schema": { "type": "number", "description": "**Search around a point — latitude.** Optional. Decimal degrees, e.g. `29.3375` (Salmiya).\n\n- Must be sent with `longitude`; together they keep only listings located close to that point, so\n expect far fewer results than the plain keyword search.\n- A point far from Kuwait (including any coordinate of `0`) finds nothing: an empty page with `total: 0`.", "minimum": -90, "maximum": 90 }, "required": false, "description": "**Search around a point — latitude.** Optional. Decimal degrees, e.g. `29.3375` (Salmiya).\n\n- Must be sent with `longitude`; together they keep only listings located close to that point, so\n expect far fewer results than the plain keyword search.\n- A point far from Kuwait (including any coordinate of `0`) finds nothing: an empty page with `total: 0`.", "name": "latitude", "in": "query" }, { "schema": { "type": "number", "description": "**Search around a point — longitude.** Optional. Decimal degrees, e.g. `48.0759` (Salmiya).\n\n- Must be sent with `latitude`; sending only one of the two is a 400.\n- Coordinates of any listing are on /listing-details (`location.latitude` / `location.longitude`).", "minimum": -180, "maximum": 180 }, "required": false, "description": "**Search around a point — longitude.** Optional. Decimal degrees, e.g. `48.0759` (Salmiya).\n\n- Must be sent with `latitude`; sending only one of the two is a 400.\n- Coordinates of any listing are on /listing-details (`location.latitude` / `location.longitude`).", "name": "longitude", "in": "query" }, { "schema": { "type": "string", "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "maxLength": 1000 }, "required": false, "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "name": "attributes", "in": "query" } ], "responses": { "200": { "description": "**Keyword search across the whole marketplace, with price, attribute, photo, video and near-a-point\nfilters.** The call for \"find me X\" when you do not know the category; to browse one category without\na keyword, use /listings.\n\nReturns `query`, `page`, `page_size`, `total`, `total_pages`, `total_is_capped`, `listings[]` and\n`placements[]`.\n\n**`total` stops at 10,000.**\n\n- For broad queries the count is reported as exactly `10000`, `total_is_capped` is `true` and\n `total_pages` is `null`; the real result set is larger and pages continue past it — walk until a page\n comes back empty. Below 10,000 the count is exact.\n- Paging reaches the first 40,000 matches (`page` × `page_size` at most 40,000); a page past the end of\n the set is an empty page, and only a page that would need rows beyond the 40,000th match is a 400\n asking you to narrow the search.\n- Multi-word and fuzzy queries match broadly, so a large `total` does not mean every row is an exact\n match; the first pages are the most relevant.\n\n**`placements`** are the sponsored listings the marketplace inserts into search results, mostly for\nvehicle queries (`car`, `سيارات`). Most queries have none.\n\n- They can be commercial banner listings (card `status: commercial_banner`, `placement: commercial`)\n and can also include a pinned listing (`placement: pinned`).\n- They are not counted in `total`, are shared out across pages in `page_size` slices and come back in a\n different order on each call (the same banner can show on page 1 and page 2).\n- They are dropped when `video_only`, `attributes`, a positive `min_price` or a near-a-point search\n (`latitude`/`longitude`) is set; `max_price`, `images_only` and `sort` keep them.\n\n**This search is catalogue-wide.** To search inside one category use /category-search — for \"Prados\nunder 8,000 KWD\": /category-search?query=prado&category_id=1971&max_price=8000 — or browse\n/listings?category_id=1971 with the same filters and no keyword.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": "prado", "page": 1, "page_size": 20, "total": 1437, "total_is_capped": false, "total_pages": 72, "listings": [ { "listing_id": 21113679, "slug": "toyota-prado-21113679McNML", "url": "https://www.q84sale.com/en/listing/toyota-prado-21113679McNML", "title": "Toyota Prado", "description_en": "Toyota Prado TX", "description_ar": "تويوتا برادو TX", "price": 8400, "currency": "KWD", "category": { "category_id": 781, "name_en": "Shuwaikh", "name_ar": "الشويخ" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1787569016411307311.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/1787569016411307311.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/1787569016411307311.png" ], "images_count": 7, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": 59, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": true, "logo": "https://media.q84sale.com/images/profile_images/Y1CKzDoDvLfE.png", "phone": "96511000033" }, "contact_phone": "96524962500", "contact_numbers": [ "96524962500" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": false, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1048 } ], "published_at": "2026-08-24 10:57:05", "sorted_at": "2026-08-24 10:57:05", "expires_at": null }, { "listing_id": 21186873, "slug": "prado-2020", "url": "https://www.q84sale.com/en/listing/prado-2020", "title": "Prado 2020", "description_en": "Prado TXL, regular agency service, original agency paint except for one piece.\nPrice 8500.\nContact number 66442327", "description_ar": "برادو TXL سيرفس منتظم الوكاله ، صبغ الوكاله ماعدا قطعه واحده \nالسعر ٨٥٠٠ \nرقم التواصل 66442327", "price": 8500, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/f8aad34a-823c-4bb8-b23e-fac819483c95.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/f8aad34a-823c-4bb8-b23e-fac819483c95.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/f8aad34a-823c-4bb8-b23e-fac819483c95.png" ], "images_count": 4, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": 311, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": false, "logo": null, "phone": "96566442327" }, "contact_phone": "96566442327", "contact_numbers": [ "96566442327" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": true, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1047 } ], "published_at": "2026-09-19 16:10:14", "sorted_at": "2026-10-07 16:10:14", "expires_at": null } ], "placements": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listings": { "get": { "tags": [ "Search" ], "operationId": "listCategoryListings", "description": "Browse one category with district, price and attribute filters.", "parameters": [ { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- A non-leaf category returns its whole subtree (`138` Toyota includes every Toyota model); a navigation-only group is a 400 naming its children.", "example": 2888, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- A non-leaf category returns its whole subtree (`138` Toyota includes every Toyota model); a navigation-only group is a 400 naming its children.", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "description": "**More categories to include alongside `category_id`.** Optional. Comma-separated category ids, e.g.\n`116` or `116,99`; up to 20, from any vertical.\n\n- The result is every listing in `category_id` OR any of these (each with its whole subtree), counted\n once in `total`. The response's `category_ids` lists the categories actually browsed.\n- The default order becomes `newest`; send `sort` for another.\n- An unknown id is a **404**; a navigation-only group is a **400** naming its children.", "maxLength": 200 }, "required": false, "description": "**More categories to include alongside `category_id`.** Optional. Comma-separated category ids, e.g.\n`116` or `116,99`; up to 20, from any vertical.\n\n- The result is every listing in `category_id` OR any of these (each with its whole subtree), counted\n once in `total`. The response's `category_ids` lists the categories actually browsed.\n- The default order becomes `newest`; send `sort` for another.\n- An unknown id is a **404**; a navigation-only group is a **400** naming its children.", "name": "category_ids", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; omit it for the category's own order (`newest` when `category_ids` is used).\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n- `premium` — listings with an active Premium add-on (card `is_premium: true`) first, then the rest\n\nIn the default order the category's pinned paid listings are left out of `listings` (they are on\n/promoted-listings). Any explicit `sort` orders them in with the rest and counts them in `total`; on\nmost categories a `district_ids` filter does the same.", "enum": [ "newest", "oldest", "price_low", "price_high", "premium" ] }, "required": false, "description": "**Result order.** Optional; omit it for the category's own order (`newest` when `category_ids` is used).\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n- `premium` — listings with an active Premium add-on (card `is_premium: true`) first, then the rest\n\nIn the default order the category's pinned paid listings are left out of `listings` (they are on\n/promoted-listings). Any explicit `sort` orders them in with the rest and counts them in `total`; on\nmost categories a `district_ids` filter does the same.", "name": "sort", "in": "query" }, { "schema": { "type": "number", "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "name": "min_price", "in": "query" }, { "schema": { "type": "number", "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "maxLength": 400 }, "required": false, "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "name": "district_ids", "in": "query" }, { "schema": { "type": "integer", "description": "**Service categories only: keep the providers serving one governorate.** Optional.\n\n- One governorate id: `2` Ahmadi, `3` Jahra, `4` Kuwait City, `5` Mubarak Al-Kabeer, `6` Farwaniyah,\n `7` Hawalli (the ids /districts lists with no parameters).\n- Keeps the providers located in that governorate **plus those serving all of Kuwait**, as the site's\n governorate page of a service category does (`…/contracting/plumber/1/hawalli--district`).\n `district_ids` instead keeps only the providers located there, so it returns fewer.\n- Works on the service categories only (plumber, electrician, AC services, pack and move, cleaning, …:\n `category_type: listings_district_filteration` on /categories); `category_id`, and every\n `category_ids` entry where offered, must be one.\n- A 400: an area or block id, a non-service category, or combining it with `district_ids`.", "minimum": 1, "maximum": 999999999 }, "required": false, "description": "**Service categories only: keep the providers serving one governorate.** Optional.\n\n- One governorate id: `2` Ahmadi, `3` Jahra, `4` Kuwait City, `5` Mubarak Al-Kabeer, `6` Farwaniyah,\n `7` Hawalli (the ids /districts lists with no parameters).\n- Keeps the providers located in that governorate **plus those serving all of Kuwait**, as the site's\n governorate page of a service category does (`…/contracting/plumber/1/hawalli--district`).\n `district_ids` instead keeps only the providers located there, so it returns fewer.\n- Works on the service categories only (plumber, electrician, AC services, pack and move, cleaning, …:\n `category_type: listings_district_filteration` on /categories); `category_id`, and every\n `category_ids` entry where offered, must be one.\n- A 400: an area or block id, a non-service category, or combining it with `district_ids`.", "name": "service_area_id", "in": "query" }, { "schema": { "type": "string", "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "maxLength": 1000 }, "required": false, "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "name": "attributes", "in": "query" } ], "responses": { "200": { "description": "**Browse one category — the marketplace's category pages, with district, price and attribute filters.**\nThe call for \"every apartment for rent in Salmiya under 400 KWD with 2 bedrooms\":\n`category_id=2888&district_ids=54&max_price=400&attributes=46:2`. Add `category_ids` to browse several\ncategories as one result set (e.g. Toyota and Nissan: `category_id=138&category_ids=116`).\n\nReturns `category_id`, `category_ids` (every category browsed), `sort` (the order applied), `page`,\n`page_size`, `total`, `total_pages` and `listings[]`.\n\n- **`total` is exact**; walk `page` to `total_pages` (or until `listings` is empty) to collect every\n listing. Only the first 40,000 can be paged (`page` × `page_size` at most 40,000) — split a larger\n category with filters.\n- **Paid placements are not in `listings`.** In the default order the category's pinned paid listings\n are left out of `listings` and of `total`; get them, with the commercial and golden slots, from\n /promoted-listings. Any explicit `sort` orders the pinned listings in with the rest and counts them in\n `total`; on most categories a `district_ids` filter does the same.\n- **Two district filters.** `district_ids` keeps listings LOCATED in the districts (every category).\n On the service categories (plumbers, movers, cleaning, …) `service_area_id` instead keeps the\n providers serving one governorate, including those serving all of Kuwait — what the site's governorate\n pages show, and usually far more providers than those located there.\n- A listing can live in several categories (a dealer category and Used Cars, for example), so de-duplicate\n by `listing_id` when you combine separate calls.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category_id": 2888, "category_ids": [ 2888 ], "sort": null, "page": 1, "page_size": 20, "total": 1186, "total_pages": 60, "listings": [ { "listing_id": 21183177, "slug": "apartment-for-rent-kwd-3", "url": "https://www.q84sale.com/en/listing/apartment-for-rent-kwd-3", "title": "Apartment For Rent — KWD 3", "description_en": "2,500-meter warehouse, fully licensed, 9-meter height, ready for entry, 10 cm concrete flooring, thermal insulator, easy and wide entrance and exit, directly from the owner.", "description_ar": "للاجار مخزن ٢٥٠٠ متر مرهص بالكامل ارتفاع ٩ متر جاهز للدخول ارصيه خرسانه ١٠سانتي عازل حراري مدخل ومخرج سهل وواسع من المالك مباشره \nFully licensed 2,500 sqm warehouse, ready for immediate move-in…", "price": 3, "currency": "KWD", "category": { "category_id": 2888, "name_en": "Apartment For Rent", "name_ar": "شقة للايجار" }, "district": { "district_id": 720, "name_en": "Block 1", "name_ar": "قطعة ١", "path_en": [ "Kuwait", "Ahmadi", "Shalehat Mina Abdullah", "Block 1" ], "path_ar": [ "الكويت", "الأحمدي", "شاليهات ميناء عبدالله", "قطعة ١" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/80359430-fbda-49d5-8e49-ab019048d376.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/80359430-fbda-49d5-8e49-ab019048d376.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/80359430-fbda-49d5-8e49-ab019048d376.png" ], "images_count": 2, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": false, "plan_id": 237, "seller": { "user_id": 1407052, "name": "bader Almutairi", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96551588223" }, "contact_phone": "96551588223", "contact_numbers": [ "96551588223" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 46, "value": 0 } ], "published_at": "2026-09-18 10:23:48", "sorted_at": "2026-10-09 10:23:48", "expires_at": "2026-10-18 10:23:48" }, { "listing_id": 21246674, "slug": "apartment-for-rent-in-salmiya-panorama-view", "url": "https://www.q84sale.com/en/listing/apartment-for-rent-in-salmiya-panorama-view", "title": "شقة للإيجار فى السالمية - إطلالة بانوراما", "description_en": "🏡 Apartment for rent in Salmiya – Panorama view\n\nA distinctive opportunity for housing in the Salmiya area in a prime location, with a wonderful panoramic view and excellent finishing.\n\nConsists of…", "description_ar": "🏡 شقة للإيجار في السالمية – إطلالة بانوراما\n\nفرصة مميزة للسكن في منطقة السالمية بموقع مميز، إطلالة بانورامية رائعة وتشطيب ممتاز.\n\nمكونة من:\nصالة\nغرفة نوم ماستر\nمطبخ\nحمام\n\n🚗 مواقف سيارات مظللة…", "price": 345, "currency": "KWD", "category": { "category_id": 2888, "name_en": "Apartment For Rent", "name_ar": "شقة للايجار" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1776185809909219036.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1776185809909219036.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/1776185809909219036.jpg" ], "images_count": 5, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": false, "plan_id": 57, "seller": { "user_id": 2420054, "name": "Oral Real Estate Office", "image": "https://media.q84sale.com/images/profile_images/1778669893744712484.png", "account_type": "normal", "is_verified": true, "logo": "https://media.q84sale.com/images/profile_images/1778669893744712484.png", "phone": "96511010530" }, "contact_phone": "96596711870", "contact_numbers": [ "96596711870" ], "phone_hidden": true, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 46, "value": 1 } ], "published_at": "2026-10-09 10:01:12", "sorted_at": "2026-10-09 10:01:12", "expires_at": "2026-11-08 10:01:12" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/category-search": { "get": { "tags": [ "Search" ], "operationId": "searchCategoryListings", "description": "Keyword search inside one category, with district, price and attribute filters.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**The keyword to look for inside the category.** Required; 1–200 characters, English or Arabic,\ne.g. `txl`, `white`, `للبيع`.\n\n- Matches listing titles and descriptions, and matching is fuzzy: `txl` also finds `TX`, `TX.L`,\n `TX-L`, `TLX` and `VXL`.\n- A multi-word query matches listings containing **any** of its words, so `total` can be much larger\n than the listings with the exact phrase. Results are ranked by relevance, so the first pages hold\n the closest matches and deep pages drift\n off-topic. To narrow, search the model's own category (e.g. Land Cruiser rather than Used Cars) or\n add filters.\n- HTML tags, script-like text and a bare `0` are refused with 400.", "example": "txl" }, "required": true, "description": "**The keyword to look for inside the category.** Required; 1–200 characters, English or Arabic,\ne.g. `txl`, `white`, `للبيع`.\n\n- Matches listing titles and descriptions, and matching is fuzzy: `txl` also finds `TX`, `TX.L`,\n `TX-L`, `TLX` and `VXL`.\n- A multi-word query matches listings containing **any** of its words, so `total` can be much larger\n than the listings with the exact phrase. Results are ranked by relevance, so the first pages hold\n the closest matches and deep pages drift\n off-topic. To narrow, search the model's own category (e.g. Land Cruiser rather than Used Cars) or\n add filters.\n- HTML tags, script-like text and a bare `0` are refused with 400.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- The whole subtree is searched: `2897` (Used Cars) covers every make and model beneath it, and a\n navigation group such as `1540` (Automotive) covers all of its children. One id per request.", "example": 1971, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- The whole subtree is searched: `2897` (Used Cars) covers every make and model beneath it, and a\n navigation group such as `1540` (Automotive) covers all of its children. One id per request.", "name": "category_id", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `20`; accepts 1–50. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "minimum": 1, "maximum": 50 }, "required": false, "description": "**Rows per page.** Default `20`; accepts 1–50. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "name": "page_size", "in": "query" }, { "schema": { "type": "number", "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "name": "min_price", "in": "query" }, { "schema": { "type": "number", "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "maxLength": 400 }, "required": false, "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "name": "district_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "maxLength": 1000 }, "required": false, "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "name": "attributes", "in": "query" } ], "responses": { "200": { "description": "**Keyword search inside one category, with district, price and attribute filters.** The call for\n\"TXL Prados in Salmiya between 8,000 and 12,000 KWD\": `query=txl&category_id=1971&district_ids=54&min_price=8000&max_price=12000`.\n/search is catalogue-wide; /listings is scoped but has no keyword — this endpoint does both.\n\nReturns `query`, `category_id`, `page`, `page_size`, `total`, `total_is_capped`, `total_pages`,\n`listings[]` and `placements[]`.\n\n- **Matching is fuzzy:** a keyword also matches spellings about one character away (`txl` finds `TX`,\n `TX.L`, `TX-L`, `TLX` and `VXL`), and a keyword in one language matches listings written in the other\n (`prado` and `برادو` find almost the same set).\n- **Results are in relevance order and cannot be sorted.** For price- or date-ordered browsing use\n /listings with `sort`.\n- **`total` stops at 10,000:** broad keywords report exactly `10000` with `total_is_capped: true` and\n `total_pages: null` — the real set is larger, so walk until a page comes back empty. Below 10,000 the\n count is exact and a walk ends on it.\n- **Multi-word keywords match any of their words**, so `total` can be much larger than the exact-phrase\n matches and deep pages drift off-topic; the first pages are the most relevant.\n- **Walking the pages:** listings with equal relevance can swap places between two page requests, so a\n full walk can show a listing twice and miss another. De-duplicate by `listing_id`; a narrower request\n (a price band, `district_ids`) that fits in fewer pages, or a second walk merged with the first,\n closes the gap.\n- **`placements`** are commercial banner listings (card `status: commercial_banner`, `placement:\n commercial`) the marketplace inserts into keyword results, mostly for vehicle queries, taken from the\n searched category and its subtree. They are not counted in `total`, are shared out across pages in\n `page_size` slices and come back in a different order on each call. Most queries have none.\n- An unknown `category_id` or district id is a **404** naming it. A navigation group (e.g. `1540`\n Automotive) is searched across all of its children.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.\n\nOn this endpoint the cards are the same as /search's cards for the same listing: `has_video`,\n`is_premium`, `seller.is_verified` and `chat_enabled` are `true`/`false`; `was_promoted`, `is_anonymous`,\n`phone_hidden` and `booking_enabled` are `null` (not reported here), as are the seller's `user_id`, `name`,\n`image` and `account_type`, `reactions_count` (with `reactions: []`), `badge_icons` and `expires_at` —\n/listing-details has all of them.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": "txl", "category_id": 1971, "page": 1, "page_size": 20, "total": 177, "total_is_capped": false, "total_pages": 9, "listings": [ { "listing_id": 21234312, "slug": "prado-21234312", "url": "https://www.q84sale.com/en/listing/prado-21234312", "title": "برادو txl", "description_en": "Prado 6 cylinder, original agency paint completely, odometer 324,000, double transmission, regular service, clean/accident-free condition, examination.", "description_ar": "برادو 6 سلندر صبغ الوكالة بالكامل \nعداد 324000 دبل قير سيرفس منتظم \nشرط الفحص", "price": 5600, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": 137, "name_en": "Saad Al-Abdulla", "name_ar": "سعد العبدالله", "path_en": [ "Kuwait", "Jahra", "Saad Al-Abdulla" ], "path_ar": [ "الكويت", "الجهراء", "سعد العبدالله" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1791122930594772188.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/1791122930594772188.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/1791122930594772188.jpg" ], "images_count": 7, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": 325, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": false, "logo": null, "phone": "96596615752" }, "contact_phone": "96596615752", "contact_numbers": [ "96596615752" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": true, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 623 } ], "published_at": "2026-10-04 14:21:40", "sorted_at": "2026-10-04 14:21:40", "expires_at": null }, { "listing_id": 21188401, "slug": "prado-21188401", "url": "https://www.q84sale.com/en/listing/prado-21188401", "title": "برادو TXL", "description_en": "For sale Prado TXL\nModel 2023\nOdometer 98 thousand\n6 cylinder\nFingerprint\nRefrigerator\nScreen rear camera\nVelvet cushions\nDoor fingerprint\nClean / accident-free condition\n( Transmission - Engine…", "description_ar": "للبيع برادو TXL \nموديل 2023 \nعداد 98 ألف \n6 سلندر \nبصمه \nثلاجه \nشاشه كاميرا خلفيه \nكشنات مخمل \nبصمة ابواب \nشرط الفحص \n( قير - ماكينه - شاصي )", "price": 9600, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": 1023, "name_en": "Block 1", "name_ar": "قطعة ١", "path_en": [ "Kuwait", "Farwaniyah", "Rai", "Block 1" ], "path_ar": [ "الكويت", "الفروانية", "الري", "قطعة ١" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1790579110908573607.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/1790579110908573607.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/1790579110908573607.jpg" ], "images_count": 9, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": 311, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": false, "logo": null, "phone": "96569002091" }, "contact_phone": "96569002091", "contact_numbers": [ "96569002091" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": true, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1061 } ], "published_at": "2026-09-20 07:25:47", "sorted_at": "2026-10-08 07:25:47", "expires_at": null } ], "placements": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/latest-listings": { "get": { "tags": [ "Search" ], "operationId": "listLatestListings", "description": "The live catalogue across every category as one roughly newest-first feed — for monitoring new listings or a bulk sync.", "parameters": [ { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–100,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- The feed runs roughly newest-first, so page 1 always holds the freshest listings; poll it to catch new ones.", "minimum": 1, "maximum": 100000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–100,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- The feed runs roughly newest-first, so page 1 always holds the freshest listings; poll it to catch new ones.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `30`; accepts 1–30. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.\n\n30 is the most one page can hold.", "minimum": 1, "maximum": 30 }, "required": false, "description": "**Rows per page.** Default `30`; accepts 1–30. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.\n\n30 is the most one page can hold.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "description": "**Narrow the feed to listings whose title or description contains this text.** Optional, English or\nArabic, e.g. `prado`.\n\n- The text is matched literally as one piece (`%` and `_` are plain characters), not word by word,\n so it is much narrower than /search.\n- Use it to watch for a specific item appearing.", "maxLength": 100 }, "required": false, "description": "**Narrow the feed to listings whose title or description contains this text.** Optional, English or\nArabic, e.g. `prado`.\n\n- The text is matched literally as one piece (`%` and `_` are plain characters), not word by word,\n so it is much narrower than /search.\n- Use it to watch for a specific item appearing.", "name": "query", "in": "query" } ], "responses": { "200": { "description": "**The live catalogue across every category as one roughly newest-first feed.** Use\nit to watch for new listings across every category, or to walk the marketplace page by page as the\nbackbone of a bulk sync (a complete collection also needs /listings — see below).\n\nReturns `query`, `page`, `page_size`, `total`, `total_pages` and `listings[]` (the standard card).\n\n- **Roughly newest-first:** rows run by `listing_id` from the highest down, but neighbouring rows can\n arrive out of order and `published_at` can step back by a few minutes. When polling for new listings,\n de-duplicate by `listing_id` and do not stop at the first id you have already seen — read the whole\n first page (or two).\n- **Paging:** pages hold at most 30 listings; every page up to `total_pages` can be read at any page\n size. Because the feed is live, a listing published while you walk it shifts later rows by one —\n de-duplicate by `listing_id`.\n- **Coverage:** this feed also reaches listings that no category page shows (many of them commercial\n banner listings), so a complete collection combines it with /listings per category and\n /business-profile-listings.\n- It cannot be narrowed to a category — for category-scoped \"newest first\" use /listings with\n `sort=newest`.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": null, "page": 1, "page_size": 30, "total": 37682, "total_pages": 1257, "listings": [ { "listing_id": 21246773, "slug": "zain-numbers-21246773", "url": "https://www.q84sale.com/en/listing/zain-numbers-21246773", "title": "رقم زين جديد 50 د.ك", "description_en": null, "description_ar": "رقم زين بحالة جديدة. السعر المطلوب 50 د.ك.", "price": 50, "currency": "KWD", "category": { "category_id": 2334, "name_en": "Zain Numbers", "name_ar": "أرقام زين" }, "district": { "district_id": 1052, "name_en": "Block 3", "name_ar": "قطعة ٣", "path_en": [ "Kuwait", "Farwaniyah", "Farwaniya", "Block 3" ], "path_ar": [ "الكويت", "الفروانية", "الفروانية", "قطعة ٣" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/26810981-fa80-4f77-a718-730364e44d3f.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/26810981-fa80-4f77-a718-730364e44d3f.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/26810981-fa80-4f77-a718-730364e44d3f.png" ], "images_count": 1, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": null, "logo": null, "phone": "96597240730" }, "contact_phone": "96597240730", "contact_numbers": [ "96597240730" ], "phone_hidden": null, "is_anonymous": false, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [], "published_at": "2026-10-09 10:40:43", "sorted_at": "2026-10-09 10:40:43", "expires_at": null }, { "listing_id": 21246772, "slug": "malibu-21246772", "url": "https://www.q84sale.com/en/listing/malibu-21246772", "title": "شيفروليه ماليبو 2017 سيدان 217 كم", "description_en": null, "description_ar": "شيفروليه ماليبو موديل ٢٠١٧ بهيكل سيدان. اللون الخارجي رمادي ونوع الوقود وقود مرن. وارد الكويت والعداد 217 كم.تم عمل هئية جديدة", "price": 1100, "currency": "KWD", "category": { "category_id": 2284, "name_en": "Malibu", "name_ar": "ماليبو" }, "district": { "district_id": 814, "name_en": "Block 2", "name_ar": "قطعة ٢", "path_en": [ "Kuwait", "Jahra", "Jahra", "Block 2" ], "path_ar": [ "الكويت", "الجهراء", "الجهراء", "قطعة ٢" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/a508b95a-a1a8-4c38-a7d0-905662a3de71.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/a508b95a-a1a8-4c38-a7d0-905662a3de71.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/a508b95a-a1a8-4c38-a7d0-905662a3de71.png" ], "images_count": 6, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": null, "logo": null, "phone": "96551547547" }, "contact_phone": "96551547547", "contact_numbers": [ "96551547547" ], "phone_hidden": null, "is_anonymous": false, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 623 } ], "published_at": "2026-10-09 10:40:51", "sorted_at": "2026-10-09 10:40:51", "expires_at": null } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listings-by-url": { "get": { "tags": [ "Search" ], "operationId": "listListingsByUrl", "description": "Paste a category page address and get its listings, with the address parsed back.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "**A 4Sale category page address, pasted as-is**, with the filters the site keeps in its query string.\nRequired.\n\n- `https://www.q84sale.com/en/automotive/used-cars/porsche/911/2` — a model, page 2\n- `https://www.q84sale.com/en/property/for-rent/apartment-for-rent/1?d=54&pf=100&pt=400&n_a46=2` —\n apartments for rent in Salmiya, 100–400 KWD, 2 rooms\n- `https://www.q84sale.com/en/contracting/plumber/1/hawalli--district` — a service category in one\n governorate\n\nHow it is read:\n\n- The deepest category in the path is used (a numeric model slug such as `911` is the model); the\n trailing number is the page.\n- A `…--district` segment names a governorate; see the response description for how it applies.\n- Applied query keys: `d`, `pf`/`pt`, `n_a`, `a`, `af`/`at`, `b_a`, `sort`,\n `c`/`s`. Anything not applied is listed in `ignored_query_keys`.\n- A single-listing address is a 400 pointing to /listing-details-by-url.", "example": "https://www.q84sale.com/en/property/for-rent/apartment-for-rent/1" }, "required": true, "description": "**A 4Sale category page address, pasted as-is**, with the filters the site keeps in its query string.\nRequired.\n\n- `https://www.q84sale.com/en/automotive/used-cars/porsche/911/2` — a model, page 2\n- `https://www.q84sale.com/en/property/for-rent/apartment-for-rent/1?d=54&pf=100&pt=400&n_a46=2` —\n apartments for rent in Salmiya, 100–400 KWD, 2 rooms\n- `https://www.q84sale.com/en/contracting/plumber/1/hawalli--district` — a service category in one\n governorate\n\nHow it is read:\n\n- The deepest category in the path is used (a numeric model slug such as `911` is the model); the\n trailing number is the page.\n- A `…--district` segment names a governorate; see the response description for how it applies.\n- Applied query keys: `d`, `pf`/`pt`, `n_a`, `a`, `af`/`at`, `b_a`, `sort`,\n `c`/`s`. Anything not applied is listed in `ignored_query_keys`.\n- A single-listing address is a 400 pointing to /listing-details-by-url.", "name": "url", "in": "query" }, { "schema": { "type": "string", "description": "**More categories to include alongside `category_id`.** Optional. Comma-separated category ids, e.g.\n`116` or `116,99`; up to 20, from any vertical.\n\n- The result is every listing in `category_id` OR any of these (each with its whole subtree), counted\n once in `total`. The response's `category_ids` lists the categories actually browsed.\n- The default order becomes `newest`; send `sort` for another.\n- An unknown id is a **404**; a navigation-only group is a **400** naming its children.", "maxLength": 200 }, "required": false, "description": "**More categories to include alongside `category_id`.** Optional. Comma-separated category ids, e.g.\n`116` or `116,99`; up to 20, from any vertical.\n\n- The result is every listing in `category_id` OR any of these (each with its whole subtree), counted\n once in `total`. The response's `category_ids` lists the categories actually browsed.\n- The default order becomes `newest`; send `sort` for another.\n- An unknown id is a **404**; a navigation-only group is a **400** naming its children.", "name": "category_ids", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- Overrides the page number in the URL; omitted, the URL's own page is used.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.\n- Overrides the page number in the URL; omitted, the URL's own page is used.\n- **Paging window:** `page` × `page_size` may be at most 40,000. A page that would need rows beyond the\n 40,000th match is a 400; narrow the request with filters (price, `attributes`, districts, a more\n specific query) to reach the rest.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Rows per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "name": "page_size", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; omit it for the category's own order (`newest` when `category_ids` is used).\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n- `premium` — listings with an active Premium add-on (card `is_premium: true`) first, then the rest\n\nIn the default order the category's pinned paid listings are left out of `listings` (they are on\n/promoted-listings). Any explicit `sort` orders them in with the rest and counts them in `total`; on\nmost categories a `district_ids` filter does the same.", "enum": [ "newest", "oldest", "price_low", "price_high", "premium" ] }, "required": false, "description": "**Result order.** Optional; omit it for the category's own order (`newest` when `category_ids` is used).\n\n- `newest` — most recently published or bumped to the top first (by the card's `sorted_at`)\n- `oldest` — earliest first (by `sorted_at`)\n- `price_low` — cheapest first; listings with no price (\"price on request\") sort before every priced one\n- `price_high` — most expensive first\n- `premium` — listings with an active Premium add-on (card `is_premium: true`) first, then the rest\n\nIn the default order the category's pinned paid listings are left out of `listings` (they are on\n/promoted-listings). Any explicit `sort` orders them in with the rest and counts them in `total`; on\nmost categories a `district_ids` filter does the same.", "name": "sort", "in": "query" }, { "schema": { "type": "number", "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Minimum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or above this value,\ne.g. `1000`.\n\n- Send it alone for \"at least\", or with `max_price` for a band.\n- A positive minimum excludes listings without a price; `0` is no restriction.\n- Accepts 0–999,999,999.", "name": "min_price", "in": "query" }, { "schema": { "type": "number", "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "minimum": 0, "maximum": 999999999 }, "required": false, "description": "**Maximum price in Kuwaiti dinar (KWD).** Optional; keeps listings priced at or below this value,\ne.g. `300` for a monthly rent.\n\n- Listings with no price (\"price on request\") count as zero and are **included** under any maximum,\n so `max_price=0` returns exactly the listings without a price.\n- `min_price` above `max_price` is a 400.\n- Accepts 0–999,999,999.", "name": "max_price", "in": "query" }, { "schema": { "type": "string", "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "maxLength": 400 }, "required": false, "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "name": "district_ids", "in": "query" }, { "schema": { "type": "string", "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "maxLength": 1000 }, "required": false, "description": "**Filter by listing attributes (year, mileage, rooms, …).** Optional. Comma-separated clauses, all of\nwhich must match (AND); up to 12. Attribute ids, types and option ids come from /category-filters.\n\n- `:` — a drop-down value, e.g. `166:624` (Year 2015)\n- `:|` — any of several values (OR), e.g. `166:1048|1056`\n- `:-` — a range, e.g. `57:0-50000` (mileage in km); open ends `57:100000-`, `57:-50000`;\n `0-0` means exactly 0\n- `:` — an exact number, e.g. `46:2` (2 rooms)\n- `:1` — a yes/no feature the seller ticked, e.g. `65:1` (pool); `:0` matches only an explicit\n \"no\", not \"doesn't have it\"\n\nExample: `166:1048|1056,57:0-80000` = 2021 or 2022 models with at most 80,000 km.\n\n- **Filterable:** drop-down, number and yes/no attributes with `scope: listing`, including\n `filterable: false` ones.\n- **Not filterable:** `text`, `file` and `multi_selection` attributes (a text value is a 400), and\n `scope: category` attributes, which never match.\n- A malformed clause is a 400 that shows the expected syntax.", "name": "attributes", "in": "query" } ], "responses": { "200": { "description": "**Paste a category page address, get its listings.** The same result as /listings, without having to\nwork out the category id, district id or filter syntax yourself: the filters the site keeps in the\naddress (district, price band, attributes, order) are applied too.\n\nReturns `parsed` — how the URL was read, so you can check it — followed by exactly what /listings\nreturns (`category_id`, `category_ids`, `sort`, `total`, `total_pages`, `listings`, …); the category's\npaid placements are on /promoted-listings.\n`category_ids` lists the categories actually browsed and `category_id` is the first of them — the\npath's category, or the first of the address's `c`/`s` categories when those replace it. `parsed`\ncarries:\n\n- `url`, `language`, `page` (the page number in the address, or `null`);\n- `category_slug`, `category_id`, `category_name_en`/`category_name_ar` — the deepest category in the\n path (also when the address's `c`/`s` keys replaced it; see `filters.category_ids`);\n- `district_slug` (the district segment of the path, if any), and `district_id`,\n `district_name_en`/`district_name_ar` — the district filter actually applied when it is a single\n district (`null` otherwise); `district_filter` says how it was applied: `listing_location` (listings\n located there) or `service_area` (a service category's governorate page: providers serving that\n governorate, including those serving all of Kuwait);\n- `filters` — every filter applied (`category_ids`, `district_ids`, `min_price`, `max_price`,\n `attributes` in this API's syntax, `sort`), whichever of the address or your parameters it came from;\n- `ignored_query_keys` and `ignored_path_segments` — the parts of the address that could not be applied\n (tracking keys such as `utm_source` are skipped silently).\n\n**A `…--district` segment** names a governorate:\n\n- On a service category (plumbers, movers, …) it keeps the providers serving that governorate, including\n those serving all of Kuwait (`district_filter: service_area`). There the site ignores the `d`, `a` and\n `b` query keys, and so does this endpoint (they are listed in `ignored_query_keys`).\n- On any other category it is applied as a district filter on where listings are located\n (`district_filter: listing_location`): `…/apartment-for-rent/1/hawalli--district` returns the same\n listings as /listings?category_id=2888&district_ids=7.\n- When `category_ids` or the address's `c`/`s` keys mix a service category with any other kind of\n category, the service-area segment is dropped, as on the site, and listed in `ignored_path_segments`.\n\n**Your parameters win over the address:**\n\n- `district_ids`, `min_price`, `max_price`, `attributes`, `sort` and `page` replace what the URL says;\n your `district_ids` also replaces a `…--district` segment.\n- `category_ids` works as on /listings — it ADDS categories to the path's category — and replaces the\n address's own `c`/`s` keys (listed in `ignored_query_keys`).\n\nA single-listing address is a 400 pointing to /listing-details-by-url; an address whose category or\ndistrict cannot be matched is a 404 saying which part did not match.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "parsed": { "url": "https://www.q84sale.com/en/property/for-rent/apartment-for-rent/1", "language": "en", "category_slug": "apartment-for-rent", "category_id": 2888, "category_name_en": "Apartment For Rent", "category_name_ar": "شقة للايجار", "page": 1, "district_slug": null, "district_id": null, "district_name_en": null, "district_name_ar": null, "district_filter": null, "filters": { "category_ids": [ 2888 ], "district_ids": [], "min_price": null, "max_price": null, "attributes": null, "sort": null }, "ignored_query_keys": [], "ignored_path_segments": [] }, "category_id": 2888, "category_ids": [ 2888 ], "sort": null, "page": 1, "page_size": 20, "total": 1186, "total_pages": 60, "listings": [ { "listing_id": 21183177, "slug": "apartment-for-rent-kwd-3", "url": "https://www.q84sale.com/en/listing/apartment-for-rent-kwd-3", "title": "Apartment For Rent — KWD 3", "description_en": "2,500-meter warehouse, fully licensed, 9-meter height, ready for entry, 10 cm concrete flooring, thermal insulator, easy and wide entrance and exit, directly from the owner.", "description_ar": "للاجار مخزن ٢٥٠٠ متر مرهص بالكامل ارتفاع ٩ متر جاهز للدخول ارصيه خرسانه ١٠سانتي عازل حراري مدخل ومخرج سهل وواسع من المالك مباشره \nFully licensed 2,500 sqm warehouse, ready for immediate move-in…", "price": 3, "currency": "KWD", "category": { "category_id": 2888, "name_en": "Apartment For Rent", "name_ar": "شقة للايجار" }, "district": { "district_id": 720, "name_en": "Block 1", "name_ar": "قطعة ١", "path_en": [ "Kuwait", "Ahmadi", "Shalehat Mina Abdullah", "Block 1" ], "path_ar": [ "الكويت", "الأحمدي", "شاليهات ميناء عبدالله", "قطعة ١" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/80359430-fbda-49d5-8e49-ab019048d376.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/80359430-fbda-49d5-8e49-ab019048d376.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/80359430-fbda-49d5-8e49-ab019048d376.png" ], "images_count": 2, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": false, "plan_id": 237, "seller": { "user_id": 1407052, "name": "bader Almutairi", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96551588223" }, "contact_phone": "96551588223", "contact_numbers": [ "96551588223" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 46, "value": 0 } ], "published_at": "2026-09-18 10:23:48", "sorted_at": "2026-10-09 10:23:48", "expires_at": "2026-10-18 10:23:48" }, { "listing_id": 21246674, "slug": "apartment-for-rent-in-salmiya-panorama-view", "url": "https://www.q84sale.com/en/listing/apartment-for-rent-in-salmiya-panorama-view", "title": "شقة للإيجار فى السالمية - إطلالة بانوراما", "description_en": "🏡 Apartment for rent in Salmiya – Panorama view\n\nA distinctive opportunity for housing in the Salmiya area in a prime location, with a wonderful panoramic view and excellent finishing.\n\nConsists of…", "description_ar": "🏡 شقة للإيجار في السالمية – إطلالة بانوراما\n\nفرصة مميزة للسكن في منطقة السالمية بموقع مميز، إطلالة بانورامية رائعة وتشطيب ممتاز.\n\nمكونة من:\nصالة\nغرفة نوم ماستر\nمطبخ\nحمام\n\n🚗 مواقف سيارات مظللة…", "price": 345, "currency": "KWD", "category": { "category_id": 2888, "name_en": "Apartment For Rent", "name_ar": "شقة للايجار" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1776185809909219036.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1776185809909219036.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/1776185809909219036.jpg" ], "images_count": 5, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": false, "plan_id": 57, "seller": { "user_id": 2420054, "name": "Oral Real Estate Office", "image": "https://media.q84sale.com/images/profile_images/1778669893744712484.png", "account_type": "normal", "is_verified": true, "logo": "https://media.q84sale.com/images/profile_images/1778669893744712484.png", "phone": "96511010530" }, "contact_phone": "96596711870", "contact_numbers": [ "96596711870" ], "phone_hidden": true, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 46, "value": 1 } ], "published_at": "2026-10-09 10:01:12", "sorted_at": "2026-10-09 10:01:12", "expires_at": "2026-11-08 10:01:12" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/promoted-listings": { "get": { "tags": [ "Search" ], "operationId": "listPromotedListings", "description": "A category's paid placements: its pinned, rotating, business, commercial and golden listings.", "parameters": [ { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- A non-leaf category returns the placements on its own first page; a navigation-only group is a 400 naming its children.", "example": 2897, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.\n- A non-leaf category returns the placements on its own first page; a navigation-only group is a 400 naming its children.", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "maxLength": 400 }, "required": false, "description": "**Limit results to one or more districts.** Optional. Comma-separated district ids from /districts,\ne.g. `54` (Salmiya) or `54,69`; any of them may match (OR). Up to 30 ids.\n\n- A district includes everything beneath it: a governorate (e.g. `7` Hawalli) covers its areas and\n blocks, an area (e.g. `54` Salmiya) covers its blocks.\n- `1` is the whole country and means **no district filter** (alone or in a list).\n- Listings posted for \"anywhere in Kuwait\" (card `district_id: null`) are left out by any district filter.\n- Governorate, area and block ids (levels 1–3) are accepted. Any other id, including the level-4 entries\n /districts lists beneath some blocks, is a **404** naming it, also when the list contains `1`.", "name": "district_ids", "in": "query" }, { "schema": { "type": "integer", "description": "**Service categories only: keep the providers serving one governorate.** Optional.\n\n- One governorate id: `2` Ahmadi, `3` Jahra, `4` Kuwait City, `5` Mubarak Al-Kabeer, `6` Farwaniyah,\n `7` Hawalli (the ids /districts lists with no parameters).\n- Keeps the providers located in that governorate **plus those serving all of Kuwait**, as the site's\n governorate page of a service category does (`…/contracting/plumber/1/hawalli--district`).\n `district_ids` instead keeps only the providers located there, so it returns fewer.\n- Works on the service categories only (plumber, electrician, AC services, pack and move, cleaning, …:\n `category_type: listings_district_filteration` on /categories); `category_id`, and every\n `category_ids` entry where offered, must be one.\n- A 400: an area or block id, a non-service category, or combining it with `district_ids`.", "minimum": 1, "maximum": 999999999 }, "required": false, "description": "**Service categories only: keep the providers serving one governorate.** Optional.\n\n- One governorate id: `2` Ahmadi, `3` Jahra, `4` Kuwait City, `5` Mubarak Al-Kabeer, `6` Farwaniyah,\n `7` Hawalli (the ids /districts lists with no parameters).\n- Keeps the providers located in that governorate **plus those serving all of Kuwait**, as the site's\n governorate page of a service category does (`…/contracting/plumber/1/hawalli--district`).\n `district_ids` instead keeps only the providers located there, so it returns fewer.\n- Works on the service categories only (plumber, electrician, AC services, pack and move, cleaning, …:\n `category_type: listings_district_filteration` on /categories); `category_id`, and every\n `category_ids` entry where offered, must be one.\n- A 400: an area or block id, a non-service category, or combining it with `district_ids`.", "name": "service_area_id", "in": "query" } ], "responses": { "200": { "description": "**The paid placements on a category's first page — the listings sellers paid to pin to the top, plus\nthe commercial, business and golden slots.** The call for \"which listings are promoted in Used Cars\nright now\": `category_id=2897`. These are the rows /listings leaves out of `listings` in its default\norder.\n\nReturns `category_id`, `total` and `placements[]`.\n\n- **`total` is the number of placements returned** — there is no paging; the category's placements all\n come back in one response, grouped by `placement`.\n- Each placement is a listing card with a `placement` label: `pinned`, `pinned_rotating` (pinned slots\n shared in rotation), `pinned_business` (pinned slots for business accounts), `commercial` (commercial\n banner listings, card `status: commercial_banner`), `business_commercial` or `golden` (the golden pin).\n A listing appears once.\n- **Filters narrow the placements as they narrow the category page.** On most categories a\n `district_ids` filter leaves no placements (the category page then orders the pinned listings in with\n the rest — /listings with the same filter returns them in `listings`). On the service categories\n (plumbers, movers, cleaning, …) `district_ids` and `service_area_id` keep the placements, narrowed to\n the area.\n- A category with no paid placements answers `total: 0` and an empty `placements`. An unknown\n `category_id` or district id is a **404** naming it.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category_id": 2897, "total": 84, "placements": [ { "listing_id": 21241943, "slug": "0-21241943", "url": "https://www.q84sale.com/en/listing/0-21241943", "title": "عبدالعزيز / مشترك بحث", "description_en": null, "description_ar": null, "price": null, "currency": "KWD", "category": { "category_id": 2897, "name_en": "Used Cars", "name_ar": "سيارات مستعملة" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1791370172355437265.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1791370172355437265.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/1791370172355437265.jpg" ], "images_count": 2, "has_video": false, "status": "commercial_banner", "is_premium": false, "was_promoted": false, "plan_id": null, "seller": { "user_id": 753793, "name": "4sale user", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": null }, "contact_phone": "+96566766907", "contact_numbers": [ "+96566766907" ], "phone_hidden": true, "is_anonymous": true, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [], "published_at": "2026-10-07 10:51:32", "sorted_at": "2026-10-07 10:51:32", "expires_at": "2026-11-07 21:00:00", "placement": "commercial" }, { "listing_id": 21241826, "slug": "0-21241826", "url": "https://www.q84sale.com/en/listing/0-21241826", "title": "عبدالله", "description_en": null, "description_ar": null, "price": null, "currency": "KWD", "category": { "category_id": 2897, "name_en": "Used Cars", "name_ar": "سيارات مستعملة" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1791367946983845120.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1791367946983845120.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/1791367946983845120.jpg" ], "images_count": 2, "has_video": false, "status": "commercial_banner", "is_premium": false, "was_promoted": false, "plan_id": null, "seller": { "user_id": 753793, "name": "4sale user", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": null }, "contact_phone": "+96597664648", "contact_numbers": [ "+96597664648" ], "phone_hidden": true, "is_anonymous": true, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": null, "attributes": [], "published_at": "2026-10-07 10:12:51", "sorted_at": "2026-10-07 10:12:51", "expires_at": "2026-11-07 21:00:00", "placement": "commercial" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/popular-listings": { "get": { "tags": [ "Search" ], "operationId": "listPopularListings", "description": "The most-viewed listings right now in each major vertical.", "responses": { "200": { "description": "**The most-viewed listings right now in each major vertical.** The marketplace's own \"popular\" rails —\nwhat buyers are looking at in Automotive, Property, Services, Electronics, Furniture and Contracting.\n\nReturns `total_sections` and `sections[]`, each with `vertical_category_id`, `title_en`/`title_ar`,\n`total` (how many listings the section holds) and up to 20 `listings` (the standard listing card).\nTakes no parameters; the ranking is the marketplace's own and refreshes on its schedule. Listings the\nmarketplace has taken down but its rails still name are left out, so a section can hold fewer than 20.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "total_sections": 6, "sections": [ { "vertical_category_id": 1540, "title_en": "All in Automotive", "title_ar": "إعلانات المحركات", "total": 8, "listings": [ { "listing_id": 21236587, "slug": "lx-21236587", "url": "https://www.q84sale.com/en/listing/lx-21236587", "title": "لكزس LX 2016 الساير الدرجه الاولى ماشي ١٨١ الف سيرفس منتظم", "description_en": "Lexus LX 2016 model, black exterior, tan interior. Kuwait imported, odometer 181,000 km. Regular service. The body has paint on two pieces: the door and the edge of the rear left fender (for cosmetic…", "description_ar": "لكزس LX موديل 2016 باللون الأسود.داخل تان وارد الكويت والعداد 181 كم. سيرفس منتظم البدي فيه صبغ قطعتين باب وطرف مدقر خلفي يسار ( للتجميل) حمايه فل بدي تحت الكفاله بيمه جديده سنه صور الفحص موجوده…", "price": 15000, "currency": "KWD", "category": { "category_id": 1895, "name_en": "LX", "name_ar": "LX" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/dc556174-fc7c-4af3-83db-7b93f1b61507.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/dc556174-fc7c-4af3-83db-7b93f1b61507.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/dc556174-fc7c-4af3-83db-7b93f1b61507.png" ], "images_count": 11, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": false, "plan_id": 311, "seller": { "user_id": 246009, "name": "ناصر فهد", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96599969938" }, "contact_phone": "96599969938", "contact_numbers": [ "96599969938" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": [ "https://static.q84sale.com/images/static/vip_icon.png" ], "attributes": [ { "attribute_id": 166, "value": 623 } ], "published_at": "2026-10-05 11:32:54", "sorted_at": "2026-10-05 11:32:54", "expires_at": "2026-11-04 11:32:54" } ] }, { "vertical_category_id": 89, "title_en": "All in Property", "title_ar": "إعلانات العقارات", "total": 6, "listings": [ { "listing_id": 21243366, "slug": "floor-21243366", "url": "https://www.q84sale.com/en/listing/floor-21243366", "title": "الجابرية", "description_en": "Residential floor with an area of 200 meters on one street. It includes 6 rooms, 2 halls, and 4 bathrooms. It contains central air conditioning, an elevator, and a domestic room. The building…", "description_ar": "دور سكني بمساحة 200 متر على شارع واحد. يضم 6 غرف و2 صالة و4 حمامات. يحتوي على تكييف مركزي ومصعد وغرفة منزلية. المبنى من دورين.", "price": 950, "currency": "KWD", "category": { "category_id": 2892, "name_en": "Floor", "name_ar": "دور كامل" }, "district": { "district_id": 392, "name_en": "Block 10", "name_ar": "قطعة ١٠", "path_en": [ "Kuwait", "Hawalli", "Jabriya", "Block 10" ], "path_ar": [ "الكويت", "حولي", "الجابرية", "قطعة ١٠" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/a4d98bfe-2636-4ab3-ae00-ffb2e07072fa.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/a4d98bfe-2636-4ab3-ae00-ffb2e07072fa.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/a4d98bfe-2636-4ab3-ae00-ffb2e07072fa.png" ], "images_count": 14, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": false, "plan_id": 237, "seller": { "user_id": 522060, "name": "بدر المطر", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96599025725" }, "contact_phone": "96599025725", "contact_numbers": [ "96599025725" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 0, "reactions": [], "badge_icons": [ "https://static.q84sale.com/images/static/vip_icon.png" ], "attributes": [ { "attribute_id": 46, "value": 6 } ], "published_at": "2026-10-07 18:26:04", "sorted_at": "2026-10-07 18:26:04", "expires_at": "2026-11-06 18:34:07" } ] } ] } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listing-details": { "get": { "tags": [ "Listings" ], "operationId": "getListingDetails", "description": "Everything about one listing by id: bilingual text, decoded attributes, coordinates, seller and promotion state.", "parameters": [ { "schema": { "type": "integer", "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "example": 21199272, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "name": "listing_id", "in": "query" } ], "responses": { "200": { "description": "**Everything about one listing by its id — the full, decoded, bilingual record.**\n\nOne record combining the listing, its decoded attributes, its seller and its promotion state:\n\n- identity & text — `listing_id`, `slug`, `url`, `status`, `state`, `title` (as posted) with\n `title_en`/`title_ar`, `description` (the full text; listing cards carry only a 200-character excerpt)\n with `description_en`/`description_ar`, `original_language` (the language the **title** was written in —\n it describes the title only, and the description can be in the other language; the other rendering of\n the title is the marketplace's machine translation), `summary_title` (the marketplace's own short title,\n e.g. make, model and year — in one fixed language per listing, Arabic or English, whatever the language\n of the rest; `null` on most listings outside cars).\n Each text is placed by the language it is actually written in: a listing with an English title and an\n Arabic description gets the Arabic text as `description_ar`, and a text that mixes both languages is\n the original in the language its translation is NOT in — so English never lands under `_ar` or\n Arabic under `_en`. The marketplace's filler \"No Description بدون وصف\" is `null`, not a description;\n- `price` + `currency` (KWD); `price` is `null` for \"price on request\", never `0`;\n- `category` — id, both names, the full `breadcrumbs` path, and `alternative_category`: a second\n category the listing is also filed under — typically a dealer's own showroom category, e.g. `3592`\n Al Sayer Car World — as `category_id`, `slug`, `name_en`, `name_ar` and its own `breadcrumbs`\n (`null` for most listings, and never a repeat of `category_id`). Browse it with /listings?category_id=\n to see that dealer's whole stock — unless the marketplace has since retired that category, which\n /listings then answers with a 404 (the same holds for a listing's main `category_id`);\n- `location` — `district_id`, both district names, `district_path_en`/`district_path_ar`\n (Kuwait → governorate → area → block). A listing placed \"anywhere in Kuwait\" has `district_id: null`,\n the names Kuwait / الكويت and the path `[\"Kuwait\"]`. Full-precision `latitude`/`longitude` when the\n seller pinned a point inside Kuwait (a pin outside the country is a typing error and is `null`),\n `precision` (the marketplace's label for that pin, e.g. `approximate`; `null` without a pin) and\n `street_name` (usually `null`);\n- media — `images` (1000 px; every image of the listing, including the second image commercial\n banners carry), `thumbnails`, `images_count`, `video_url`, `video_thumbnail`. The marketplace's \"no\n image\" placeholder picture is never published — a listing without photos has `images: []`;\n- `attributes` — every attribute decoded: `name_en`/`name_ar`, the raw `value`, and\n `value_label_en`/`value_label_ar` (e.g. Year → `2015`) or `unit_en` for numbers (e.g. Mileage → km).\n A `text` attribute keeps its text exactly (a plate number `00000` stays `\"00000\"`). An attribute the\n seller never answered has `value: null`. An attribute the listing's category no longer defines (left\n from a category the listing was moved out of) keeps its raw `value` with `name_en`, `type` and the\n labels `null`;\n- `seller` — `user_id`, `name`, `image`, `phone`, `account_type` (e.g. `normal`, `automotive_office`,\n `property_office`), `is_verified`, `business_profile_slug` (the seller's business profile — open it\n with /business-profile-details; `null` for a private seller), `business_directory` (the business\n directory that profile is listed in, as /business-profiles `directory`), `member_since`, `followers`,\n `active_listings_count` (the active-listing count the marketplace reports for the account; it can be\n higher than what /seller-listings returns, because some listings are not listed there), `status`,\n `website_url`. `seller.phone` is the phone of the ACCOUNT that posted the listing — the key\n /seller-listings takes — not necessarily a number the ad asks buyers to call (see `contact`). It is\n published also when `contact.phone_hidden` is `true`; it is `null` when the listing sits on the\n marketplace's own placeholder account;\n- `contact` — `phone` (the number to call: the first number the ad displays, or the account's phone\n when the ad lists none and the seller has not hidden it; `null` when the seller hid the number and\n the ad displays none), every `contact_numbers` entry, `phone_hidden` (`true` when the seller asked the\n marketplace to hide the account's number; `seller.phone` still carries it), `is_anonymous`,\n `chat_enabled`, `voip_enabled`;\n- `promotion` — the paid-promotion state: `plan_id`, `bundle_name`/`bundle_price`, `bundle_features`\n (`[{text, expired}]` — each feature of the bought bundle, `expired: true` once it has run out),\n `paid` (`true` for any paid plan, including a plain Basic or Extra plan), `is_premium` (`true` only\n when a Premium add-on is active — the same meaning as `is_premium` on the list cards; a paid plan\n without that add-on is `paid: true, is_premium: false`), `is_pinned` (`true` while a pinning add-on\n is active, a golden pin included — the listing then sits in that category's pinned placements, a\n golden pin in its `golden` placement; `false` for a listing only queued for a pin and once\n `pinning_ends_at` has passed), `pinning_waiting` (`true` while a `waiting`\n add-on is active, i.e. the listing is queued for a pin in that add-on's category), `will_pin_at` (when\n the queued pin starts — reported only for a listing that already holds another pin; `null` for a\n listing whose only add-on is `waiting`), `pinning_ends_at` (the marketplace's pin timer — one per\n listing, also set on a listing only queued for a pin), `video_paid` (whether a paid video add-on was\n bought), `was_promoted`, `addons` (the paid add-ons\n active on the listing, each listed once: `[{type, category_id, category_name, screen}]`, `type` e.g.\n `pinning`, `pinning_shuffle`, `golden_pin`, `premium`, `waiting`; `screen` e.g. `Hot Zone`; a pinning\n or golden-pin add-on whose pin has ended is not listed), `pinned_in` (`[{category_id, until}]` —\n every category the listing is pinned in right now, one entry each, from its active pinning and\n golden-pin add-ons; empty when `is_pinned` is\n `false`. `until` is the pin timer for the category the marketplace attributes it to and `null` for\n the other pinned categories) and\n `auto_repost`. `bundle_name`, `bundle_features[].text` and `addons[].category_name` are in English;\n- `view_count`, `created_at`, `published_at`, `sorted_at` (last bumped), `expires_at`, `source` (the\n marketplace's label for where the ad was posted from, e.g. `q8car-office`) and `source_app` (the app\n brand the listing was posted from, as served).\n\n**Dates:** `created_at`, `published_at`, `sorted_at`, `expires_at` and the pin times (`will_pin_at`,\n`pinning_ends_at`, `pinned_in[].until`) are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them, the\nsame as on listing cards. `seller.member_since` uses the same format.\n\n**Reading a listing counts as a view.** The marketplace counts every full read of a listing as one\nview, exactly as it counts a buyer opening the listing page, so each call adds 1 to the listing's\npublic view count, and the `view_count` it returns already includes that view. /listing-score,\n/similar-listings and /listing-views do not count a view, and neither does a **404**.\n\nA listing that does not exist, was removed, or is still a draft is a **404**. If part of the record\ncannot be read this time, its fields are `null` (or empty) and `partial_errors` (`[{part, status,\nmessage}]`) names it. `status` is `404` when that part is not available for this listing, `503` when\nit is temporarily unavailable (retry shortly) and `500` otherwise. The parts:\n\n- `promotion` — the pin timer (`pinning_ends_at` / `will_pin_at` / `pinned_in[].until`) and `video_paid`;\n- `media` — `thumbnails`, `video_thumbnail`;\n- `summary_title`, `contact.voip_enabled`;\n- `seller_profile` — `seller.account_type`, `is_verified`, `business_profile_slug`, `business_directory`,\n `active_listings_count`, `website_url`;\n- `district` — the district names and path;\n- `alternative_category`.\n\nAn empty `partial_errors` means the record is complete.\n\nNext: /seller-listings?phone={seller.phone}, /similar-listings, /listing-score.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "listing_id": 21199272, "slug": "prado-21199272", "url": "https://www.q84sale.com/en/listing/prado-21199272", "status": "normal", "state": "active", "title": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله 🔥", "title_en": "For sale Prado model 2015, clean/accident-free condition completely, odometer 163, agency service 🔥", "title_ar": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله 🔥", "summary_title": "تويوتا, برادو - ٢٠١٥", "description": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله وبحاله المصنع 🔥\nالسعر 5900\n\n\n\n\nكاش كار للسيارات - العارضيه الحرفية\nبيع - شراء - تثمين -البيع كاش او اقساط او ايجار تملك للمتعدين 40 %", "description_en": "For sale Prado model 2015, clean/accident-free condition completely, odometer 163, agency service, and in factory condition 🔥\nPrice 5900\n\nCash Car for cars - Al-Ardiya Industrial\nSell - Purchase - Va…", "description_ar": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله وبحاله المصنع 🔥\nالسعر 5900\n\n\n\n\nكاش كار للسيارات - العارضيه الحرفية\nبيع - شراء - تثمين -البيع كاش او اقساط او ايجار تملك للمتعدين 40 %", "original_language": "ar", "price": 5900, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو", "breadcrumbs": [ { "category_id": 1540, "slug": "automotive", "name_en": "Automotive", "name_ar": "محركات" }, { "category_id": 2897, "slug": "used-cars", "name_en": "Used Cars", "name_ar": "سيارات مستعملة" }, { "category_id": 138, "slug": "toyota", "name_en": "Toyota", "name_ar": "تويوتا" }, { "category_id": 1971, "slug": "prado", "name_en": "Prado", "name_ar": "برادو" } ], "alternative_category": { "category_id": 3034, "slug": "cash-car", "name_en": "Cash Car", "name_ar": "كاش كار", "breadcrumbs": [ { "category_id": 1540, "slug": "automotive", "name_en": "Automotive", "name_ar": "محركات" }, { "category_id": 376, "slug": "car-offices", "name_en": "Car Offices", "name_ar": "مكاتب السيارات" }, { "category_id": 3034, "slug": "cash-car", "name_en": "Cash Car", "name_ar": "كاش كار" } ] } }, "location": { "district_id": 1028, "district_name_en": "Block 4", "district_name_ar": "قطعة ٤", "district_path_en": [ "Kuwait", "Farwaniyah", "Ardihya", "Block 4" ], "district_path_ar": [ "الكويت", "الفروانية", "العارضية", "قطعة ٤" ], "latitude": 29.290379, "longitude": 47.890259, "precision": null, "street_name": null }, "images": [ "https://media.q84sale.com/images/user_adv/resize1000/1779832696676912262.jpg", "https://media.q84sale.com/images/user_adv/resize1000/1779832697949820251.jpg" ], "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize/1779832696676912262.jpg", "https://media.q84sale.com/images/user_adv/resize/1779832697949820251.jpg" ], "images_count": 8, "video_url": null, "video_thumbnail": null, "attributes": [ { "attribute_id": 166, "name_en": "Year", "name_ar": "سنة الصنع", "type": "drop_down", "value": 624, "value_label_en": "2015", "value_label_ar": "٢٠١٥", "unit_en": null, "unit_ar": null }, { "attribute_id": 59, "name_en": "Color Exterior", "name_ar": "اللون الخارجي", "type": "drop_down", "value": 609, "value_label_en": "Gray", "value_label_ar": "رمادي", "unit_en": null, "unit_ar": null } ], "seller": { "user_id": 2152353, "name": "Cash Car Office", "image": "https://media.q84sale.com/images/profile_images/1779611719162832470.png", "phone": "96511010037", "account_type": "automotive_office", "is_verified": true, "business_profile_slug": "cash-car-189", "business_directory": "car-offices", "member_since": "2022-08-30 09:19:56", "followers": 35, "active_listings_count": 36, "status": "active", "website_url": null }, "contact": { "phone": "96567780777", "contact_numbers": [ "96567780777", "96551560009" ], "phone_hidden": true, "is_anonymous": false, "chat_enabled": true, "voip_enabled": false }, "promotion": { "plan_id": 59, "bundle_name": null, "bundle_price": null, "bundle_features": [], "paid": false, "is_premium": false, "is_pinned": false, "was_promoted": false, "pinning_waiting": false, "will_pin_at": null, "pinning_ends_at": null, "video_paid": false, "addons": [], "pinned_in": [], "auto_repost": false }, "view_count": 1089, "created_at": "2026-09-22 21:28:02", "published_at": "2026-09-22 21:28:08", "sorted_at": "2026-09-22 21:28:08", "expires_at": "2026-10-22 21:28:08", "source": "q8car-office", "source_app": "q8car", "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listing-details-by-url": { "get": { "tags": [ "Listings" ], "operationId": "getListingDetailsByUrl", "description": "Paste a listing page address and get the full listing record.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 2000, "description": "**A 4Sale listing page address, pasted as-is.** Required. English or Arabic pages, with or without\n`https://` and `www.`, in any letter case:\n\n- `https://www.q84sale.com/en/listing/prado-21199272`\n- `https://www.q84sale.com/ar/listing/prado-21199272`\n- `https://www.q84sale.com/en/commercial-listing/0-20871367` (a commercial banner listing)\n- `https://www.q84sale.com/en/listing/21199272` or `…/listing/archived/21199272` (the id alone)\n\nHow it is read:\n\n- The slug decides the listing (upper or lower case): a slug whose number belongs to another listing\n (`prado-21196026`) is a **404**, never that other listing.\n- An address that names two different listings (`/listing/21199272/prado-21196026`,\n `/listing/21199272/21196026`) is a **404**.\n- A category page address is a 400 pointing to /listings-by-url.", "example": "https://www.q84sale.com/en/listing/prado-21199272" }, "required": true, "description": "**A 4Sale listing page address, pasted as-is.** Required. English or Arabic pages, with or without\n`https://` and `www.`, in any letter case:\n\n- `https://www.q84sale.com/en/listing/prado-21199272`\n- `https://www.q84sale.com/ar/listing/prado-21199272`\n- `https://www.q84sale.com/en/commercial-listing/0-20871367` (a commercial banner listing)\n- `https://www.q84sale.com/en/listing/21199272` or `…/listing/archived/21199272` (the id alone)\n\nHow it is read:\n\n- The slug decides the listing (upper or lower case): a slug whose number belongs to another listing\n (`prado-21196026`) is a **404**, never that other listing.\n- An address that names two different listings (`/listing/21199272/prado-21196026`,\n `/listing/21199272/21196026`) is a **404**.\n- A category page address is a 400 pointing to /listings-by-url.", "name": "url", "in": "query" } ], "responses": { "200": { "description": "**Paste a listing page address, get the full listing.** The same record as /listing-details, without\nextracting the id yourself.\n\nReturns `parsed` (`url`, `language`, `slug`, `listing_id` — how the address was read) and `listing` —\nthe full record described below. The listing is found by the SLUG in the address (matched exactly,\nupper or lower case): a slug whose number belongs to a different listing (`…/listing/prado-21196026`\nwhen 21196026 is a Telluride) is a **404**, never that other listing. An address that carries only the\nid (`…/listing/21199272`, `…/listing/archived/21199272`) is read by id. An address whose slug ends in\none id while another path segment carries a different one (`…/listing/gardener-21201671/21201656`),\nor that carries two different bare ids (`…/listing/21199272/21196026`), names two listings and is a\n**404**. A category page address is a 400 pointing to /listings-by-url.\n\nOne record combining the listing, its decoded attributes, its seller and its promotion state:\n\n- identity & text — `listing_id`, `slug`, `url`, `status`, `state`, `title` (as posted) with\n `title_en`/`title_ar`, `description` (the full text; listing cards carry only a 200-character excerpt)\n with `description_en`/`description_ar`, `original_language` (the language the **title** was written in —\n it describes the title only, and the description can be in the other language; the other rendering of\n the title is the marketplace's machine translation), `summary_title` (the marketplace's own short title,\n e.g. make, model and year — in one fixed language per listing, Arabic or English, whatever the language\n of the rest; `null` on most listings outside cars).\n Each text is placed by the language it is actually written in: a listing with an English title and an\n Arabic description gets the Arabic text as `description_ar`, and a text that mixes both languages is\n the original in the language its translation is NOT in — so English never lands under `_ar` or\n Arabic under `_en`. The marketplace's filler \"No Description بدون وصف\" is `null`, not a description;\n- `price` + `currency` (KWD); `price` is `null` for \"price on request\", never `0`;\n- `category` — id, both names, the full `breadcrumbs` path, and `alternative_category`: a second\n category the listing is also filed under — typically a dealer's own showroom category, e.g. `3592`\n Al Sayer Car World — as `category_id`, `slug`, `name_en`, `name_ar` and its own `breadcrumbs`\n (`null` for most listings, and never a repeat of `category_id`). Browse it with /listings?category_id=\n to see that dealer's whole stock — unless the marketplace has since retired that category, which\n /listings then answers with a 404 (the same holds for a listing's main `category_id`);\n- `location` — `district_id`, both district names, `district_path_en`/`district_path_ar`\n (Kuwait → governorate → area → block). A listing placed \"anywhere in Kuwait\" has `district_id: null`,\n the names Kuwait / الكويت and the path `[\"Kuwait\"]`. Full-precision `latitude`/`longitude` when the\n seller pinned a point inside Kuwait (a pin outside the country is a typing error and is `null`),\n `precision` (the marketplace's label for that pin, e.g. `approximate`; `null` without a pin) and\n `street_name` (usually `null`);\n- media — `images` (1000 px; every image of the listing, including the second image commercial\n banners carry), `thumbnails`, `images_count`, `video_url`, `video_thumbnail`. The marketplace's \"no\n image\" placeholder picture is never published — a listing without photos has `images: []`;\n- `attributes` — every attribute decoded: `name_en`/`name_ar`, the raw `value`, and\n `value_label_en`/`value_label_ar` (e.g. Year → `2015`) or `unit_en` for numbers (e.g. Mileage → km).\n A `text` attribute keeps its text exactly (a plate number `00000` stays `\"00000\"`). An attribute the\n seller never answered has `value: null`. An attribute the listing's category no longer defines (left\n from a category the listing was moved out of) keeps its raw `value` with `name_en`, `type` and the\n labels `null`;\n- `seller` — `user_id`, `name`, `image`, `phone`, `account_type` (e.g. `normal`, `automotive_office`,\n `property_office`), `is_verified`, `business_profile_slug` (the seller's business profile — open it\n with /business-profile-details; `null` for a private seller), `business_directory` (the business\n directory that profile is listed in, as /business-profiles `directory`), `member_since`, `followers`,\n `active_listings_count` (the active-listing count the marketplace reports for the account; it can be\n higher than what /seller-listings returns, because some listings are not listed there), `status`,\n `website_url`. `seller.phone` is the phone of the ACCOUNT that posted the listing — the key\n /seller-listings takes — not necessarily a number the ad asks buyers to call (see `contact`). It is\n published also when `contact.phone_hidden` is `true`; it is `null` when the listing sits on the\n marketplace's own placeholder account;\n- `contact` — `phone` (the number to call: the first number the ad displays, or the account's phone\n when the ad lists none and the seller has not hidden it; `null` when the seller hid the number and\n the ad displays none), every `contact_numbers` entry, `phone_hidden` (`true` when the seller asked the\n marketplace to hide the account's number; `seller.phone` still carries it), `is_anonymous`,\n `chat_enabled`, `voip_enabled`;\n- `promotion` — the paid-promotion state: `plan_id`, `bundle_name`/`bundle_price`, `bundle_features`\n (`[{text, expired}]` — each feature of the bought bundle, `expired: true` once it has run out),\n `paid` (`true` for any paid plan, including a plain Basic or Extra plan), `is_premium` (`true` only\n when a Premium add-on is active — the same meaning as `is_premium` on the list cards; a paid plan\n without that add-on is `paid: true, is_premium: false`), `is_pinned` (`true` while a pinning add-on\n is active, a golden pin included — the listing then sits in that category's pinned placements, a\n golden pin in its `golden` placement; `false` for a listing only queued for a pin and once\n `pinning_ends_at` has passed), `pinning_waiting` (`true` while a `waiting`\n add-on is active, i.e. the listing is queued for a pin in that add-on's category), `will_pin_at` (when\n the queued pin starts — reported only for a listing that already holds another pin; `null` for a\n listing whose only add-on is `waiting`), `pinning_ends_at` (the marketplace's pin timer — one per\n listing, also set on a listing only queued for a pin), `video_paid` (whether a paid video add-on was\n bought), `was_promoted`, `addons` (the paid add-ons\n active on the listing, each listed once: `[{type, category_id, category_name, screen}]`, `type` e.g.\n `pinning`, `pinning_shuffle`, `golden_pin`, `premium`, `waiting`; `screen` e.g. `Hot Zone`; a pinning\n or golden-pin add-on whose pin has ended is not listed), `pinned_in` (`[{category_id, until}]` —\n every category the listing is pinned in right now, one entry each, from its active pinning and\n golden-pin add-ons; empty when `is_pinned` is\n `false`. `until` is the pin timer for the category the marketplace attributes it to and `null` for\n the other pinned categories) and\n `auto_repost`. `bundle_name`, `bundle_features[].text` and `addons[].category_name` are in English;\n- `view_count`, `created_at`, `published_at`, `sorted_at` (last bumped), `expires_at`, `source` (the\n marketplace's label for where the ad was posted from, e.g. `q8car-office`) and `source_app` (the app\n brand the listing was posted from, as served).\n\n**Dates:** `created_at`, `published_at`, `sorted_at`, `expires_at` and the pin times (`will_pin_at`,\n`pinning_ends_at`, `pinned_in[].until`) are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them, the\nsame as on listing cards. `seller.member_since` uses the same format.\n\n**Reading a listing counts as a view.** The marketplace counts every full read of a listing as one\nview, exactly as it counts a buyer opening the listing page, so each call adds 1 to the listing's\npublic view count, and the `view_count` it returns already includes that view. /listing-score,\n/similar-listings and /listing-views do not count a view, and neither does a **404**.\n\nA listing that does not exist, was removed, or is still a draft is a **404**. If part of the record\ncannot be read this time, its fields are `null` (or empty) and `partial_errors` (`[{part, status,\nmessage}]`) names it. `status` is `404` when that part is not available for this listing, `503` when\nit is temporarily unavailable (retry shortly) and `500` otherwise. The parts:\n\n- `promotion` — the pin timer (`pinning_ends_at` / `will_pin_at` / `pinned_in[].until`) and `video_paid`;\n- `media` — `thumbnails`, `video_thumbnail`;\n- `summary_title`, `contact.voip_enabled`;\n- `seller_profile` — `seller.account_type`, `is_verified`, `business_profile_slug`, `business_directory`,\n `active_listings_count`, `website_url`;\n- `district` — the district names and path;\n- `alternative_category`.\n\nAn empty `partial_errors` means the record is complete.\n\nNext: /seller-listings?phone={seller.phone}, /similar-listings, /listing-score.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "parsed": { "url": "https://www.q84sale.com/en/listing/prado-21199272", "language": "en", "slug": "prado-21199272", "listing_id": 21199272 }, "listing": { "listing_id": 21199272, "slug": "prado-21199272", "url": "https://www.q84sale.com/en/listing/prado-21199272", "status": "normal", "state": "active", "title": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله 🔥", "title_en": "For sale Prado model 2015, clean/accident-free condition completely, odometer 163, agency service 🔥", "title_ar": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله 🔥", "summary_title": "تويوتا, برادو - ٢٠١٥", "description": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله وبحاله المصنع 🔥\nالسعر 5900\n\n\n\n\nكاش كار للسيارات - العارضيه الحرفية\nبيع - شراء - تثمين -البيع كاش او اقساط او ايجار تملك للمتعدين 40 %", "description_en": "For sale Prado model 2015, clean/accident-free condition completely, odometer 163, agency service, and in factory condition 🔥\nPrice 5900\n\nCash Car for cars - Al-Ardiya Industrial\nSell - Purchase - Va…", "description_ar": "للبيع برادو موديل ٢٠١٥ شرط الفحص بل الكامل عداد ١٦٣ سيرفس وكاله وبحاله المصنع 🔥\nالسعر 5900\n\n\n\n\nكاش كار للسيارات - العارضيه الحرفية\nبيع - شراء - تثمين -البيع كاش او اقساط او ايجار تملك للمتعدين 40 %", "original_language": "ar", "price": 5900, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو", "breadcrumbs": [ { "category_id": 1540, "slug": "automotive", "name_en": "Automotive", "name_ar": "محركات" }, { "category_id": 2897, "slug": "used-cars", "name_en": "Used Cars", "name_ar": "سيارات مستعملة" }, { "category_id": 138, "slug": "toyota", "name_en": "Toyota", "name_ar": "تويوتا" }, { "category_id": 1971, "slug": "prado", "name_en": "Prado", "name_ar": "برادو" } ], "alternative_category": { "category_id": 3034, "slug": "cash-car", "name_en": "Cash Car", "name_ar": "كاش كار", "breadcrumbs": [ { "category_id": 1540, "slug": "automotive", "name_en": "Automotive", "name_ar": "محركات" }, { "category_id": 376, "slug": "car-offices", "name_en": "Car Offices", "name_ar": "مكاتب السيارات" }, { "category_id": 3034, "slug": "cash-car", "name_en": "Cash Car", "name_ar": "كاش كار" } ] } }, "location": { "district_id": 1028, "district_name_en": "Block 4", "district_name_ar": "قطعة ٤", "district_path_en": [ "Kuwait", "Farwaniyah", "Ardihya", "Block 4" ], "district_path_ar": [ "الكويت", "الفروانية", "العارضية", "قطعة ٤" ], "latitude": 29.290379, "longitude": 47.890259, "precision": null, "street_name": null }, "images": [ "https://media.q84sale.com/images/user_adv/resize1000/1779832696676912262.jpg", "https://media.q84sale.com/images/user_adv/resize1000/1779832697949820251.jpg" ], "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize/1779832696676912262.jpg", "https://media.q84sale.com/images/user_adv/resize/1779832697949820251.jpg" ], "images_count": 8, "video_url": null, "video_thumbnail": null, "attributes": [ { "attribute_id": 166, "name_en": "Year", "name_ar": "سنة الصنع", "type": "drop_down", "value": 624, "value_label_en": "2015", "value_label_ar": "٢٠١٥", "unit_en": null, "unit_ar": null }, { "attribute_id": 59, "name_en": "Color Exterior", "name_ar": "اللون الخارجي", "type": "drop_down", "value": 609, "value_label_en": "Gray", "value_label_ar": "رمادي", "unit_en": null, "unit_ar": null } ], "seller": { "user_id": 2152353, "name": "Cash Car Office", "image": "https://media.q84sale.com/images/profile_images/1779611719162832470.png", "phone": "96511010037", "account_type": "automotive_office", "is_verified": true, "business_profile_slug": "cash-car-189", "business_directory": "car-offices", "member_since": "2022-08-30 09:19:56", "followers": 35, "active_listings_count": 36, "status": "active", "website_url": null }, "contact": { "phone": "96567780777", "contact_numbers": [ "96567780777", "96551560009" ], "phone_hidden": true, "is_anonymous": false, "chat_enabled": true, "voip_enabled": false }, "promotion": { "plan_id": 59, "bundle_name": null, "bundle_price": null, "bundle_features": [], "paid": false, "is_premium": false, "is_pinned": false, "was_promoted": false, "pinning_waiting": false, "will_pin_at": null, "pinning_ends_at": null, "video_paid": false, "addons": [], "pinned_in": [], "auto_repost": false }, "view_count": 1090, "created_at": "2026-09-22 21:28:02", "published_at": "2026-09-22 21:28:08", "sorted_at": "2026-09-22 21:28:08", "expires_at": "2026-10-22 21:28:08", "source": "q8car-office", "source_app": "q8car", "partial_errors": [] } } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listing-score": { "get": { "tags": [ "Listings" ], "operationId": "getListingScore", "description": "The marketplace's quality score for a listing, broken down by factor with improvement advice.", "parameters": [ { "schema": { "type": "integer", "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "example": 21199272, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "name": "listing_id", "in": "query" } ], "responses": { "200": { "description": "**The marketplace's own quality score for a listing, with the reasons and how to improve it.** Use it\nto audit listing quality, rank a seller's inventory, or explain why a listing underperforms.\n\nReturns `listing_id`, `score_available`, `overall_score` (0–100), `contact_actions_count` (the\nmarketplace's own count of contact actions — calls to action — on it) and `components[]` — one per scored factor\n(`title`, `description`, `image`, `cleanliness` (readability), `lexical_diversity` (word variety)),\neach with `score`, `label_en`/`label_ar`, `explanation_en`/`explanation_ar` and\n`recommendation_en`/`recommendation_ar`.\n\n**A listing the marketplace has not scored is not an error:** it returns 200 with\n`score_available: false`, `overall_score: null` and an empty `components` list. The marketplace does\nnot score every listing — commercial banner ads are never scored, and ordinary listings can stay\nunscored for days or weeks, so this is not only a very new listing. (The marketplace itself reports\nsuch a listing's score as `0`; that placeholder is never published as a real score.)\n\n**`contact_actions_count` is not a live figure.**\n\n- The marketplace recomputes it periodically, so it can stay `0` for a day or more while buyers are\n already calling.\n- It is a different metric from /listing-views `contact_clicks`, and the two do not agree on older\n listings either. For up-to-date click counts use /listing-views.\n- It is reported for unscored listings too, and is `null` for a listing the marketplace has not\n processed yet (typically one only minutes old).\n\nA listing id that does not exist, a removed listing or a draft is a **404**. Reading the score does not\ncount as a view of the listing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "listing_id": 21199272, "score_available": true, "overall_score": 80, "contact_actions_count": 0, "components": [ { "component": "image", "label_en": "Image Appeal", "label_ar": "جاذبية الصور", "score": 100, "explanation_en": "How attractive and trustworthy your photos look.", "explanation_ar": "قديش صورك جذابة وتعطي انطباع موثوق.", "recommendation_en": "Excellent — you uploaded 8 images. Multiple high-quality images boost trust.", "recommendation_ar": "ممتاز — أضفت 8 صورة. عدة صور عالية الجودة تعزز الثقة." }, { "component": "cleanliness", "label_en": "Readability", "label_ar": "سهولة القراءة", "score": 100, "explanation_en": "How easy your text is to read (e.g., minimal emojis, typos).", "explanation_ar": "قديش النص سهل القراءة (رموز تعبيرية قليلة وأخطاء إملائية قليلة).", "recommendation_en": "Content is clean.", "recommendation_ar": "المحتوى نظيف." } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/listing-views": { "get": { "tags": [ "Listings" ], "operationId": "getListingViews", "description": "A listing's view history by day and hour, and how often buyers used its contact buttons.", "parameters": [ { "schema": { "type": "integer", "description": "**The listing whose statistics to read — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, …); it is also\n the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- Only listings currently on the marketplace are served: an unknown, expired or removed id is a **404**\n (checked first, because 4Sale's own analytics answers any id). This route adds no view.", "example": 21199272, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The listing whose statistics to read — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, …); it is also\n the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- Only listings currently on the marketplace are served: an unknown, expired or removed id is a **404**\n (checked first, because 4Sale's own analytics answers any id). This route adds no view.", "name": "listing_id", "in": "query" } ], "responses": { "200": { "description": "**How many people viewed a listing — day by day and hour by hour since it was published — and how\noften buyers tapped its contact buttons.** The marketplace's own statistics for the listing.\nReading them does not add a view.\n\nReturns `listing_id`, `total_views`, `first_day`, `last_day`, `days[]`, `contact_clicks` and\n`partial_errors`.\n\n- `total_views` is the listing's view count as its day-by-day history records it — the sum of\n `days[].views`. On recent listings it equals the `view_count` /listing-details reports; on older\n listings that counter can run somewhat higher, because it includes views the history does not record.\n- `days[]` — one entry per day that had views (a day without views is absent), oldest first: `date`\n (`YYYY-MM-DD`), `views` and `hourly` (24 counts, index 0 = 00:00–00:59). The current day is still counting.\n- `contact_clicks` — `total` and `by_type[]`, one entry per contact action with its `total` and a\n `daily[]` series (`date`, `count`): `phone_call` and `call_icon` (two call counters the\n marketplace records separately), `whatsapp` and `chat` (in-app chat). A type nobody used is\n `total: 0` with an empty `daily`.\n- `partial_errors` lists any contact counter that could not be read (`part` `contact_clicks.`);\n `contact_clicks.total` is then `null` rather than an undercount.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "listing_id": 21199272, "total_views": 1098, "first_day": "2026-09-22", "last_day": "2026-10-09", "days": [ { "date": "2026-09-22", "views": 110, "hourly": [ 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 21, 69, 20 ] }, { "date": "2026-09-23", "views": 556, "hourly": [ 3, 7, 3, 4, 9, 7, 65, 54, 37, 8, 6, 65, 71, 1, 7, 3, 27, 48, 21, 7, 4, 9, 34, 56 ] } ], "contact_clicks": { "total": 86, "by_type": [ { "type": "phone_call", "total": 12, "daily": [ { "date": "2026-09-23", "count": 6 }, { "date": "2026-09-26", "count": 1 }, { "date": "2026-09-27", "count": 3 }, { "date": "2026-10-04", "count": 2 } ] }, { "type": "call_icon", "total": 25, "daily": [ { "date": "2026-09-23", "count": 9 }, { "date": "2026-09-24", "count": 1 }, { "date": "2026-09-25", "count": 1 }, { "date": "2026-09-26", "count": 2 }, { "date": "2026-09-27", "count": 2 }, { "date": "2026-10-02", "count": 4 }, { "date": "2026-10-04", "count": 6 } ] }, { "type": "whatsapp", "total": 40, "daily": [ { "date": "2026-09-22", "count": 1 }, { "date": "2026-09-23", "count": 14 }, { "date": "2026-09-24", "count": 6 }, { "date": "2026-09-25", "count": 12 }, { "date": "2026-09-28", "count": 1 }, { "date": "2026-10-03", "count": 1 }, { "date": "2026-10-05", "count": 1 }, { "date": "2026-10-08", "count": 2 }, { "date": "2026-10-09", "count": 2 } ] }, { "type": "chat", "total": 9, "daily": [ { "date": "2026-09-22", "count": 3 }, { "date": "2026-09-23", "count": 5 }, { "date": "2026-09-24", "count": 1 } ] } ] }, "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/similar-listings": { "get": { "tags": [ "Listings" ], "operationId": "listSimilarListings", "description": "Listings the marketplace recommends alongside one listing.", "parameters": [ { "schema": { "type": "integer", "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "example": 21199272, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The listing — a numeric 4Sale listing id.** Required.\n\n- Every listing card carries it as `listing_id` (/search, /listings, /latest-listings, /seller-listings, …).\n- It is also the number at the end of a listing page address (`…/listing/prado-21199272` → `21199272`).\n- An id that does not exist returns **404**.", "name": "listing_id", "in": "query" } ], "responses": { "200": { "description": "**Listings the marketplace recommends alongside one listing** — its \"you may also like\" rail, usually\nfrom the same category. Use it for comparables and alternatives.\n\nReturns `listing_id`, `category_id` (the source listing's category), `total` and up to 10 `listings`\n(the standard listing card; the source listing itself is excluded). The selection is the marketplace's\nand varies from call to call. A listing still filed in a category the marketplace has since retired\ngets the recommendations of its nearest parent category that is still live, which can be an empty\nlist (`category_id` stays the listing's own). An unknown, removed or draft listing is a **404**.\nReading recommendations does not count as a view of the listing.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "listing_id": 21199272, "category_id": 1971, "total": 10, "listings": [ { "listing_id": 21208866, "slug": "prado-21208866", "url": "https://www.q84sale.com/en/listing/prado-21208866", "title": "تويوتا برادو كم السياره شرط الفحص من الدعاميه للدعاميه ا", "description_en": "Toyota Prado 2019 model, Kuwait imported. Odometer 120,000 km, automatic transmission. Exterior color brown, interior beige, and seats velvet. Body condition is excellent and there is no sunroof. The…", "description_ar": "تويوتا برادو موديل 2019 وارد الكويت. العداد 120000 كم وناقل الحركة أوتوماتيكي. اللون الخارجي بني والداخلي بيج، والمقاعد مخمل. حالة الهيكل ممتازة ولا توجد فتحة سقف. السياره شرط الفحص من الدعاميه…", "price": 8300, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/d72512c5-0159-4b3a-b802-fc797f261165.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/d72512c5-0159-4b3a-b802-fc797f261165.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/d72512c5-0159-4b3a-b802-fc797f261165.png" ], "images_count": 13, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": false, "plan_id": 325, "seller": { "user_id": 714275, "name": "muhanaad hamaad", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96599552441" }, "contact_phone": "96594474476", "contact_numbers": [ "96594474476" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 1, "reactions": [ { "type": "LIKE", "count": 1 } ], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 997 } ], "published_at": "2026-09-26 13:20:09", "sorted_at": "2026-09-26 13:20:09", "expires_at": "2026-10-26 13:20:09" }, { "listing_id": 21173104, "slug": "prado-21173104", "url": "https://www.q84sale.com/en/listing/prado-21173104", "title": "برادو 2022 كامل المواصفات بحالة فوق الممتازة", "description_en": "Prado model 2022, Kuwait imported. Odometer 117,000 km, exterior color silver - 6 cylinder with leather seats and sunroof. Equipped with Bluetooth and navigation - blind spot - sensors, front and…", "description_ar": "برادو موديل 2022 وارد الكويت. العداد117000كم واللون الخارجي سلفر - 6 سلندر مع مقاعد جلد وفتحة سقف . مزود ببلوتوث ونافيجشن - نقطة العمياء - وسنسرات وإيرباج أمامية وجانبية وتحكم سكان - كشافات - سلة…", "price": 9750, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": 417, "name_en": "Block 11", "name_ar": "قطعة ١١", "path_en": [ "Kuwait", "Hawalli", "Salmiya", "Block 11" ], "path_ar": [ "الكويت", "حولي", "السالمية", "قطعة ١١" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1789751868951732147.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1789751868951732147.jpg", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize450/1789751868951732147.jpg" ], "images_count": 9, "has_video": false, "status": "normal", "is_premium": false, "was_promoted": false, "plan_id": 311, "seller": { "user_id": 2456878, "name": "Abu Marwan", "image": null, "account_type": "normal", "is_verified": false, "logo": null, "phone": "96599098450" }, "contact_phone": "96599098450", "contact_numbers": [ "96599098450" ], "phone_hidden": false, "is_anonymous": false, "chat_enabled": true, "booking_enabled": false, "reactions_count": 1, "reactions": [ { "type": "LIKE", "count": 1 } ], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1056 } ], "published_at": "2026-09-14 16:08:49", "sorted_at": "2026-10-06 17:23:36", "expires_at": "2026-10-14 16:08:49" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/seller-listings": { "get": { "tags": [ "Sellers" ], "operationId": "listSellerListings", "description": "The active listings of one seller account as the marketplace lists them (it leaves some pinned ones out), found by the seller's phone number.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 30, "description": "**The seller account's phone number.** Required. Take it from `seller.phone` on /listing-details or\non any listing card.\n\n- Accepted as `96511010037`, `+965 1101 0037`, `0096511010037` or the 8-digit local number, in\n Western, Arabic-Indic (`٩٦٥١١٠١٠٠٣٧`) or Persian digits.\n- A number no marketplace account uses is a **404**; an account with no active listings returns\n `total: 0`.\n- A malformed number — too short or long, or containing anything but digits, spaces and\n `+ - ( ) .` — is a 400.", "example": "96566669657" }, "required": true, "description": "**The seller account's phone number.** Required. Take it from `seller.phone` on /listing-details or\non any listing card.\n\n- Accepted as `96511010037`, `+965 1101 0037`, `0096511010037` or the 8-digit local number, in\n Western, Arabic-Indic (`٩٦٥١١٠١٠٠٣٧`) or Persian digits.\n- A number no marketplace account uses is a **404**; an account with no active listings returns\n `total: 0`.\n- A malformed number — too short or long, or containing anything but digits, spaces and\n `+ - ( ) .` — is a 400.", "name": "phone", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `30`; accepts 1–30. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.\n\n30 is the most one page can hold.", "minimum": 1, "maximum": 30 }, "required": false, "description": "**Rows per page.** Default `30`; accepts 1–30. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.\n\n30 is the most one page can hold.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The active listings of one seller account, as the marketplace lists them** — a dealer's inventory,\nor what a private seller has up. Use it to size a seller, spot a dealer posting as a private seller, or\ncollect a shop's stock.\n\nReturns `phone` (normalised), `page`, `page_size`, `total`, `total_pages`, `listings[]`,\n`pinned_total` and `pinned_listings[]` (both lists hold the standard card).\n\n- `listings` pages through the seller's counted list: `total` and `total_pages` count exactly these\n rows, for the `page_size` you send, on every page (a page past the end is empty and still reports\n the real `total`).\n- The seller's **pinned** (paid, promoted) listings are mostly kept out of that counted list by the\n marketplace, so they come separately: all of them in `pinned_listings` on page 1 (an empty array on\n later pages), counted by `pinned_total` on every page. They carry `placement: \"pinned\"`\n (`\"commercial\"` for a commercial banner). A seller whose only live ad is pinned has `total: 0` and\n one pinned listing.\n- The seller's whole list = all pages of `listings` plus page 1's `pinned_listings`. A pinned listing\n is sometimes ALSO in the counted list, so de-duplicate by `listing_id` when you merge them.\n- **The marketplace's seller list is not complete:** it leaves some live listings out of both lists —\n mostly pinned ones — so a seller with live pinned ads can show `total: 0` and `pinned_total: 0`. Such a\n listing still opens on /listing-details, whose `seller.phone` is this number. For the same reason\n `seller.active_listings_count` on /listing-details can be higher than `total` here.\n\n`seller.phone` identifies the ACCOUNT that posted a listing — on this endpoint it is the number you\nqueried, since every row belongs to that account; `contact_numbers` on a card are the numbers the ad\ndisplays, which can differ (a dealer with several sales lines). This feed carries no seller name or\nseller image, and the rows in `listings` carry no description text, so those card fields are `null`\nhere; every row carries its district, and `pinned_listings` carry their description. Open\n/listing-details for the full record.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "phone": "96566669657", "page": 1, "page_size": 30, "total": 87, "total_pages": 3, "listings": [ { "listing_id": 21210807, "slug": "wrangler-21210807", "url": "https://www.q84sale.com/en/listing/wrangler-21210807", "title": "جيب رانقلر سبورت 2018", "description_en": null, "description_ar": null, "price": 2900, "currency": "KWD", "category": { "category_id": 2149, "name_en": "Wrangler", "name_ar": "رانجلر" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/566ba437-0374-4efa-ba44-ca1c9fe1c5b3.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/566ba437-0374-4efa-ba44-ca1c9fe1c5b3.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/566ba437-0374-4efa-ba44-ca1c9fe1c5b3.png" ], "images_count": 7, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": null, "logo": null, "phone": "96566669657" }, "contact_phone": "96599170413", "contact_numbers": [ "96599170413" ], "phone_hidden": true, "is_anonymous": true, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 996 } ], "published_at": "2026-09-27 07:26:46", "sorted_at": "2026-10-09 07:26:46", "expires_at": null }, { "listing_id": 21210206, "slug": "prado-21210206", "url": "https://www.q84sale.com/en/listing/prado-21210206", "title": "تويوتا برادو 2024 شرط الفحص كامل", "description_en": null, "description_ar": null, "price": 13600, "currency": "KWD", "category": { "category_id": 1971, "name_en": "Prado", "name_ar": "برادو" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/0c3c0aea-777a-455a-b95f-e45a168a9993.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/0c3c0aea-777a-455a-b95f-e45a168a9993.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/0c3c0aea-777a-455a-b95f-e45a168a9993.png" ], "images_count": 7, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": null, "logo": null, "phone": "96566669657" }, "contact_phone": "96550906073", "contact_numbers": [ "96550906073" ], "phone_hidden": true, "is_anonymous": true, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1078 } ], "published_at": "2026-09-26 21:19:04", "sorted_at": "2026-10-08 21:19:04", "expires_at": null } ], "pinned_total": 1, "pinned_listings": [ { "listing_id": 21245322, "slug": "t2-21245322", "url": "https://www.q84sale.com/en/listing/t2-21245322", "title": "للبيع جيتور T2 بحالة الوكالة", "description_en": null, "description_ar": "جيب جيتور T2 \nالموديل 2025 \nعداد 70 الف \nتحت الكفاله \nاعلى المواصفات\n شاشه كبيرة \nمقاس 15.6 تدعم \nCarPlay- \nAuto Andod\nالمقاس 10.25\nدخول ذكي \nبصمة تشغيل\nتحكم سكان \nمثبت سرعه \nسناسر أماميه \nسناسر…", "price": 7700, "currency": "KWD", "category": { "category_id": 5531, "name_en": "T2", "name_ar": "T2" }, "district": { "district_id": null, "name_en": "Kuwait", "name_ar": "الكويت", "path_en": [ "Kuwait" ], "path_ar": [ "الكويت" ] }, "image": "https://media.q84sale.com/images/user_adv/resize1000/8cab1414-e1ae-4ad0-bf9a-c37608f08564.png", "thumbnail": "https://media.q84sale.com/images/user_adv/resize300/8cab1414-e1ae-4ad0-bf9a-c37608f08564.png", "thumbnails": [ "https://media.q84sale.com/images/user_adv/resize300/8cab1414-e1ae-4ad0-bf9a-c37608f08564.png" ], "images_count": 8, "has_video": false, "status": "normal", "is_premium": true, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": null, "is_verified": null, "logo": null, "phone": "96566669657" }, "contact_phone": "96590966871", "contact_numbers": [ "96590966871" ], "phone_hidden": true, "is_anonymous": true, "chat_enabled": true, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 1344 } ], "published_at": "2026-10-08 14:50:44", "sorted_at": "2026-10-08 14:50:44", "expires_at": null, "placement": "pinned" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/business-profiles": { "get": { "tags": [ "Sellers" ], "operationId": "listBusinessProfiles", "description": "Find the dealers, offices and service companies on the marketplace — by the categories they have listings in, or by business directory.", "parameters": [ { "schema": { "type": "string", "description": "**Find the businesses active in these categories.** Send this OR `directory` (exactly one).\n\n- One or more category ids from /categories, comma-separated, e.g. `2897` (Used Cars), `808` (Property\n For Rent) or `2897,808`; up to 20.\n- A vertical id such as `1540` (Automotive) covers the businesses of every category beneath it.\n- An id that is not a category is a **404**.\n- Pre-filled with `2897` so the first test call works; clear it when you use `directory`, or the\n request has both and is a 400.", "maxLength": 200, "example": "2897" }, "required": false, "description": "**Find the businesses active in these categories.** Send this OR `directory` (exactly one).\n\n- One or more category ids from /categories, comma-separated, e.g. `2897` (Used Cars), `808` (Property\n For Rent) or `2897,808`; up to 20.\n- A vertical id such as `1540` (Automotive) covers the businesses of every category beneath it.\n- An id that is not a category is a **404**.\n- Pre-filled with `2897` so the first test call works; clear it when you use `directory`, or the\n request has both and is a 400.", "name": "category_ids", "in": "query" }, { "schema": { "type": "string", "description": "**List every business in one business directory** — including businesses with no listing up right\nnow and parent businesses whose listings are posted by their branches, which `category_ids` cannot\nreach. Send this OR `category_ids` (exactly one).\n\n- `car-offices`\n- `property-offices`\n- `dealerships`\n- `electronics-shops`\n- `car-garages-1`\n\nEach profile's `directory` field carries the same values. A value that is not a slug (spaces,\npunctuation, markup) is a **400**; any other unknown directory is a **404**.", "maxLength": 100 }, "required": false, "description": "**List every business in one business directory** — including businesses with no listing up right\nnow and parent businesses whose listings are posted by their branches, which `category_ids` cannot\nreach. Send this OR `category_ids` (exactly one).\n\n- `car-offices`\n- `property-offices`\n- `dealerships`\n- `electronics-shops`\n- `car-garages-1`\n\nEach profile's `directory` field carries the same values. A value that is not a slug (spaces,\npunctuation, markup) is a **400**; any other unknown directory is a **404**.", "name": "directory", "in": "query" } ], "responses": { "200": { "description": "**Find the businesses — car dealers, real-estate offices, service companies — on the marketplace.** The\ndirectory of shop profiles, two ways in (send exactly one; neither or both is a 400):\n\n- `category_ids` — the businesses that currently have listings in those categories, busiest first,\n with `matching_listings_count` (how many of their listings fall in the categories you asked for) and\n `is_verified`;\n- `directory` — every business a business directory lists, in the directory's own order, whether or\n not it has listings up right now. The directory list does not report verification or listing counts,\n so `is_verified` and `matching_listings_count` are `null` there.\n\nThe two routes overlap but neither contains the other. Only the directory has businesses with no\ncurrent listings, and parent businesses whose stock is posted by their branches (the branches, not the\nparent, appear in `category_ids` results). Some active businesses are filed under a category but not\nlisted by their directory.\n\nReturns `category_ids` (or `null`), `directory` (or `null`), `total`, `profiles[]` and `partial_errors`.\nEach profile has `profile_id`, `slug`, `name` (the English record's name) and `name_ar` (the Arabic\nrecord's name) — each as the business entered it, so a few businesses that entered them the other way\nround have an Arabic `name` (`باورسبورتس-720`: `name` `باورسبورتس`, `name_ar` `Power Sports`) — plus\n`logo`, `is_verified`, `matching_listings_count` and `directory` (the business directory it belongs to,\ne.g. `car-offices`, `property-offices`; `null` for a business that is in none). The whole matching list\nis returned in one response — neither route pages. If the Arabic names cannot be read, every `name_ar`\nis `null` and `partial_errors` names `name_ar`; an empty `partial_errors` means the response is complete.\n\nNext: /business-profile-details?slug= for the profile, /business-profile-listings?slug= for its stock.\nA category with no businesses returns an empty list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category_ids": [ 2897 ], "directory": null, "total": 135, "profiles": [ { "profile_id": 433, "slug": "hetten-for-cars-433", "name": "Hetten for cars", "name_ar": "حطين للسيارات", "logo": "https://media.q84sale.com/images/profile_images/17439448281068290492.png", "is_verified": true, "matching_listings_count": 229, "directory": "car-offices" }, { "profile_id": 147, "slug": "abrag-qrain-1-147", "name": "Abrag Qrain 1", "name_ar": "شركة أبراج القرين ١ لبيع وشراء السيارات", "logo": "https://media.q84sale.com/images/profile_images/1741296354499836038.png", "is_verified": true, "matching_listings_count": 156, "directory": "car-offices" } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/business-profile-details": { "get": { "tags": [ "Sellers" ], "operationId": "getBusinessProfileDetails", "description": "One business profile: identity, contact numbers, verification and branches.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 150, "description": "**The business profile's slug**, e.g. `aayan-kuwait` or `hetten-for-cars-433`. Required.\n\n- Take it from the `slug` field of /business-profiles (or `seller.business_profile_slug` on\n /listing-details) exactly as published.\n- Slugs can contain `&`, dots and Arabic letters (`fouad-alghanim-&-sons-345`, `باورسبورتس-720`);\n URL-encode it in the query string.\n- Letters and digits in any script plus `.`, `_`, `-` and `&` are accepted; anything else is a 400,\n and a slug that does not exist is a **404**.", "example": "aayan-kuwait" }, "required": true, "description": "**The business profile's slug**, e.g. `aayan-kuwait` or `hetten-for-cars-433`. Required.\n\n- Take it from the `slug` field of /business-profiles (or `seller.business_profile_slug` on\n /listing-details) exactly as published.\n- Slugs can contain `&`, dots and Arabic letters (`fouad-alghanim-&-sons-345`, `باورسبورتس-720`);\n URL-encode it in the query string.\n- Letters and digits in any script plus `.`, `_`, `-` and `&` are accepted; anything else is a 400,\n and a slug that does not exist is a **404**.", "name": "slug", "in": "query" } ], "responses": { "200": { "description": "**One business profile: identity, contact numbers, verification and branches.** The shop page of a\ndealer, office or service company.\n\nReturns `profile_id`, `user_id`, `slug`, `name` (the English record's name), `name_ar` (the Arabic\nrecord's name), `logo`, `cover_image`, `about`, `member_since`, `contact_numbers[]`, `is_verified`,\n`booking_enabled`, `default_tab`, `branches[]` and `partial_errors`. Both names are as the business\nentered them; a few businesses entered them the other way round (`باورسبورتس-720` has the Arabic\n`name` `باورسبورتس` and `name_ar` `Power Sports`).\n\n- `branches[]` — the business's sub-profiles, each with `branch_id`, `user_id`, `slug`, `name`, `name_ar`\n and `booking_enabled`. A branch is a location (`aayan-kuwait` → `aayan-kuwait-qrain-32`, …) or a\n department (`fk-auto-parts-&-services-634` → `offers-653`, `battery-636`, …) with its own account, and\n its `slug` works on this endpoint and on /business-profile-listings like any profile's. A business\n without sub-profiles has an empty list.\n- `user_id` — the profile's own account; `null` for a parent business with no account of its own\n (`aayan-kuwait`). A business with branches shows its branches' stock (see below), so its listings\n are not tied to `user_id`.\n- `partial_errors` — a part that could not be read this time (`branches`, `name_ar`, `branches.name_ar`)\n is `null` and named here; the profile itself is still returned.\n\n`member_since` is the day the business joined, as `YYYY-MM-DD HH:MM:SS`, as 4Sale serves it.\n\nThe business's listings are on /business-profile-listings?slug=. For a parent business that list is its\nbranches' listings (`yusuf-a.-alghanim-and-sons-37` shows the same listings as its branch `shuwaikh-38`),\nso a card's `seller.phone` there is the posting branch's number, not necessarily one of `contact_numbers`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "profile_id": 453, "user_id": null, "slug": "aayan-kuwait", "name": "Aayan Kuwait", "name_ar": "أعيان الكويت", "logo": "https://media.q84sale.com/images/profile_images/1746712358918686223.png", "cover_image": null, "about": null, "member_since": "2016-11-23 21:00:00", "contact_numbers": [ "9651880066" ], "is_verified": true, "booking_enabled": false, "default_tab": null, "branches": [ { "branch_id": 32, "user_id": 1340335, "slug": "aayan-kuwait-qrain-32", "name": "Aayan Kuwait-Qrain", "name_ar": "أعيان الكويت - اسواق القرين", "booking_enabled": false }, { "branch_id": 34, "user_id": 1340339, "slug": "aayan-kuwait-rai-34", "name": "Aayan Kuwait-Rai", "name_ar": "أعيان الكويت - الري", "booking_enabled": false } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/business-profile-listings": { "get": { "tags": [ "Sellers" ], "operationId": "listBusinessProfileListings", "description": "A business profile's full inventory, paginated with an exact total.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 150, "description": "**The business profile's slug**, e.g. `hetten-for-cars-433`. Required.\n\n- Take it from the `slug` field of /business-profiles (or `seller.business_profile_slug` on\n /listing-details) exactly as published.\n- Slugs can contain `&`, dots and Arabic letters (`fouad-alghanim-&-sons-345`, `باورسبورتس-720`);\n URL-encode it in the query string.\n- Letters and digits in any script plus `.`, `_`, `-` and `&` are accepted; anything else is a 400,\n and a slug that does not exist is a **404**.", "example": "hetten-for-cars-433" }, "required": true, "description": "**The business profile's slug**, e.g. `hetten-for-cars-433`. Required.\n\n- Take it from the `slug` field of /business-profiles (or `seller.business_profile_slug` on\n /listing-details) exactly as published.\n- Slugs can contain `&`, dots and Arabic letters (`fouad-alghanim-&-sons-345`, `باورسبورتس-720`);\n URL-encode it in the query string.\n- Letters and digits in any script plus `.`, `_`, `-` and `&` are accepted; anything else is a 400,\n and a slug that does not exist is a **404**.", "name": "slug", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.", "minimum": 1, "maximum": 40000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–40,000.\n\n- Walk pages until `listings` comes back empty; a page past the end returns an empty `listings` array,\n not an error.", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Rows per page.** Default `30`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Rows per page.** Default `30`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` in the response is computed for the page size you send, so keep it constant while\nwalking pages.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**A business profile's full inventory, paginated.** Every listing a dealer, office or service company\nhas up, with an exact `total`.\n\nReturns `slug` (in its canonical lower-case form), `page`, `page_size`, `total`, `total_pages`,\n`listings[]` (the standard card) and `partial_errors`. Some\nof a business's listings appear on no category page, so this is also one of the three routes a complete\ncatalogue collection needs (with /listings and /latest-listings). A parent business with branches lists\nits branches' stock here; each branch's `slug` (from /business-profile-details) also works on its own.\n\nDescriptions come in both languages, as on /listing-details: an ad written in Arabic has its Arabic\noriginal in `description_ar` and the marketplace's English translation in `description_en` (and the\nother way round). A description with no letters at all (e.g. just `2017`) is published once, in\n`description_en`. If the Arabic texts cannot be read, the page is still served with the English texts\nonly (an Arabic ad then has just its English translation, with `description_ar: null`) and\n`partial_errors` names `description_ar`; an empty `partial_errors` means the page is complete.\n\nEvery listing card has the same shape on every endpoint: `listing_id`, `slug`, `url`, `title`,\n`description_en`/`description_ar`, `price` + `currency` (KWD), `category` (id + both names), `district`\n(id, both names and its path `path_en`/`path_ar`), `image`, `thumbnail`, `thumbnails`, `images_count`,\n`has_video`, `status`, `is_premium`, `was_promoted`, `plan_id`, `seller` (`user_id`, `name`, `image`,\n`account_type`, `is_verified`, `logo`, `phone`), `contact_phone`, `contact_numbers`, `phone_hidden`,\n`is_anonymous`, `chat_enabled`, `booking_enabled`, `reactions_count` with its per-type breakdown `reactions`\n(`[{type, count}]`, e.g. `LIKE`), `badge_icons`, `attributes`, `published_at`, `sorted_at` (when it was last\nbumped to the top) and `expires_at`. A row that a paid placement put on the list also carries `placement`\n(`pinned`, `pinned_rotating`, `pinned_business`, `commercial`, `business_commercial` or `golden`); other rows\nhave no `placement` key. A card is a selection-level summary: open /listing-details for the full description,\nevery image, the decoded attributes, coordinates and promotion state.\n\n- `published_at`, `sorted_at` and `expires_at` are `YYYY-MM-DD HH:MM:SS`, as 4Sale serves them.\n- `description_en` / `description_ar` each hold text in the language it is actually written in — never\n Arabic under the English name. Most feeds carry the seller's own text plus the marketplace's machine\n translation of it, so usually both are filled: a listing written in Arabic has its original in\n `description_ar` and the translation in `description_en`, and the other way round. Where a feed carries\n only the original (/latest-listings, the `pinned_listings` of /seller-listings) or a listing has no\n translation, the other language is `null`. A bilingual text is published as the Arabic version when no\n separate Arabic text exists. On a card each is a short excerpt: a text over 200 characters is cut to at\n most 200 (at a word break where possible) and ends in `…`. Call /listing-details for the full text.\n- The yes/no flags (`has_video`, `is_premium`, `was_promoted`, `is_anonymous`, `phone_hidden`,\n `chat_enabled`, `booking_enabled`, `seller.is_verified`) are `true`/`false` where the feed reports them\n and `null` where it does not; `badge_icons` (e.g. the VIP badge) is `null` on feeds that never report\n badges. Any other field a given feed does not carry is `null` too.\n- `phone_hidden` — `true` when the seller asked the marketplace to hide the account's number. `seller.phone`\n still carries the account number in that case; `contact_phone` / `contact_numbers` are the numbers the\n ad itself displays. `null` means the feed does not report the flag reliably: /search, /category-search,\n /latest-listings, /seller-listings and /business-profile-listings (a `true` can still appear there).\n- `is_premium` is `true` when the listing has an active Premium add-on, not merely a paid plan. It means\n the same as `promotion.is_premium` on /listing-details, where `promotion.paid` is the \"any paid plan\" flag.\n- `booking_enabled` — the listing can be booked in the app (daily rentals, chalets, …).\n- `plan_id` — the id of the listing's posting plan, as 4Sale serves it; there is no lookup route for it.\n- `price` is `null` for \"price on request\". On category browse (/listings, /listings-by-url), the popular\n rails and /similar-listings a price is rounded down to whole dinars (4.5 shows as 4, and a price under\n 1 KWD can show as `null`); /search, /category-search, /latest-listings, /seller-listings and\n /listing-details carry the exact price.\n- `image` / `thumbnail` are `null` when the listing has no photo — the marketplace's \"no image\" picture\n is not passed off as one — and `images_count` is then `0`. A listing with only a video shows the\n video's thumbnail as `image`, with `images_count: null`.\n- `district` — a real district carries the same `district_id` and names on every endpoint (the names\n /districts and /listing-details give it, so a block is named e.g. `Block 3`) and its full path from\n country to block in `path_en` / `path_ar`, e.g. `[\"Kuwait\", \"Hawalli\", \"Salmiya\", \"Block 3\"]` /\n `[\"الكويت\", \"حولي\", \"السالمية\", \"قطعة ٣\"]` — the same path /listing-details publishes as\n `location.district_path_en` / `location.district_path_ar`. A listing posted for \"anywhere in Kuwait\" has\n `district_id: null`, the names Kuwait / الكويت and the path `[\"Kuwait\"]` / `[\"الكويت\"]`. Business-profile\n inventory carries no district: every `district` field is `null` there (/listing-details has it). The\n path is also `null` in the rare case it cannot be looked up at that moment.\n- `status` is the status the feed reports for the row: mostly `normal`; paid rows can carry `pinned`,\n `commercial_banner` or `golden_pin`, and a counted row of /seller-listings can be `waiting` (queued for\n a pin). It is not a placement label — a seller's `pinned_listings` rows say `normal` — so use\n `placement` to tell paid rows apart. Every counted row of /search and /latest-listings is `normal`.\n The listing's own state is `status` on /listing-details.\n- `seller.account_type` is the feed's own seller label: `null` on /search, /category-search,\n /latest-listings and /seller-listings, `normal` on most other feeds even for dealer offices, `business` on\n business-profile inventory. For the kind of account use `seller.account_type` on /listing-details\n (`normal`, `automotive_office`, `property_office`, `4sale_realty`, …), or `seller.is_verified` and\n `seller.logo`.\n- `contact_phone` is the listing's own contact number (it can differ from `seller.phone`, the account's\n number).\n- `category` is the category the row was listed under: a dealer's listing can show the dealer's\n showroom category here while /listing-details reports its main category (with the showroom as\n `alternative_category`). Its names are those /categories gives; a category the marketplace has retired\n keeps its names where they are still known and otherwise has `null` names. /listing-details carries\n the breadcrumb.\n- A card's `attributes` are the few summary attributes the marketplace shows on the card (year and\n mileage, rooms and area, …) as raw `{attribute_id, value}` pairs — decode them with /category-filters;\n the complete, decoded set is on /listing-details. A value with leading zeros (a plate number) stays text.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "slug": "hetten-for-cars-433", "page": 1, "page_size": 30, "total": 221, "total_pages": 8, "listings": [ { "listing_id": 21245952, "slug": "traverse-21245952", "url": "https://www.q84sale.com/en/listing/traverse-21245952", "title": "ترافيرس ٢٠١٢ بحالة جيدة", "description_en": "For sale Chevrolet Traverse - Model 2012 - Kuwait agency imported - Odometer 357 thousand. In good condition - everything works well - selling as is, and whoever wants to perform an examination is…", "description_ar": "للبيع شيفروليه ترافيرس - موديل ٢٠١٢ - وارد وكالة الكويت- عداد ٣٥٧ ألف \nبحالة جيدة - كل شيء يعمل بصورة جيدة - البيع عالمنظور و اللي بيفحص على حسابه حياه", "price": 650, "currency": "KWD", "category": { "category_id": 1938, "name_en": "Traverse", "name_ar": "ترافيرس" }, "district": { "district_id": null, "name_en": null, "name_ar": null, "path_en": null, "path_ar": null }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1791488115139817040.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1791488115139817040.jpg", "thumbnails": [], "images_count": 10, "has_video": null, "status": "normal", "is_premium": null, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": "business", "is_verified": null, "logo": null, "phone": "96511010297" }, "contact_phone": "96558881110", "contact_numbers": [ "96558881110" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 627 } ], "published_at": "2026-10-08 19:36:51", "sorted_at": "2026-10-08 19:36:51", "expires_at": "2026-11-07 19:36:51" }, { "listing_id": 21245846, "slug": "5-series-21245846", "url": "https://www.q84sale.com/en/listing/5-series-21245846", "title": "بي ام 520i موديل ٢٠١٦ ماشي ٨٥ الف بحالة ممتازة جدا", "description_en": "For sale BMW 520i - Model 2016 - Kuwait Agency imported - Odometer only 84 thousand - Regular agency service until today - In agency condition\nFull specifications - Sunroof - Big screen - Navigation…", "description_ar": "للبيع بي ام 520i - موديل ٢٠١٦ - وارد وكالة الكويت- عداد فقط ٨٤ الف - سيرفيس وكالة منتظم الى اليوم - بحالة الوكالة\nكامل المواصفات- فتحة سقف- شاشة كبيرة - نافيجيشن- كاميرا- سناسر - كراسي جلد كهربائية…", "price": 3750, "currency": "KWD", "category": { "category_id": 1868, "name_en": "5 Series", "name_ar": "الفئة الخامسة" }, "district": { "district_id": null, "name_en": null, "name_ar": null, "path_en": null, "path_ar": null }, "image": "https://media.q84sale.com/images/user_adv/resize1000/1791484588794004458.jpg", "thumbnail": "https://media.q84sale.com/images/user_adv/resize450/1791484588794004458.jpg", "thumbnails": [], "images_count": 10, "has_video": null, "status": "normal", "is_premium": null, "was_promoted": null, "plan_id": null, "seller": { "user_id": null, "name": null, "image": null, "account_type": "business", "is_verified": null, "logo": null, "phone": "96511010297" }, "contact_phone": "96558881110", "contact_numbers": [ "96558881110" ], "phone_hidden": null, "is_anonymous": null, "chat_enabled": null, "booking_enabled": null, "reactions_count": null, "reactions": [], "badge_icons": null, "attributes": [ { "attribute_id": 166, "value": 623 } ], "published_at": "2026-10-08 18:37:26", "sorted_at": "2026-10-08 18:37:26", "expires_at": "2026-11-07 18:37:26" } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/directory-search": { "get": { "tags": [ "Sellers" ], "operationId": "searchDirectoryBusinesses", "description": "Search the business directory — restaurants, cafés, clinics, salons and other local businesses — with opening hours and tags.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**What to look for — a business name or kind, in English or Arabic.** e.g. `cafe`, `clinic`,\n`pharmacy`, `مطعم`. Required; 1–200 characters. Matches business names, descriptions and tags.\nHTML tags and script-like text are refused with 400.", "example": "cafe" }, "required": true, "description": "**What to look for — a business name or kind, in English or Arabic.** e.g. `cafe`, `clinic`,\n`pharmacy`, `مطعم`. Required; 1–200 characters. Matches business names, descriptions and tags.\nHTML tags and script-like text are refused with 400.", "name": "query", "in": "query" }, { "schema": { "type": "string", "description": "**Limit results to one directory category**, by its slug. Optional; case-insensitive. Every business\ncarries its own as `category.slug`; an unknown slug is a **404** that lists the valid ones.\n\n- Food and shopping: `restaurants-cafes`, `grocery-supermarkets`, `shopping`, `fashion`\n- Health and care: `healthcare`, `beauty-spa`, `fitness-sports`, `pet-services`\n- Vehicles and home: `automotive`, `car-garages`, `home-services`, `real-estate`\n- Services: `professional-business-services`, `financial-services`, `technology`, `education`\n- Leisure: `entertainment`, `travel-tourism`", "maxLength": 100 }, "required": false, "description": "**Limit results to one directory category**, by its slug. Optional; case-insensitive. Every business\ncarries its own as `category.slug`; an unknown slug is a **404** that lists the valid ones.\n\n- Food and shopping: `restaurants-cafes`, `grocery-supermarkets`, `shopping`, `fashion`\n- Health and care: `healthcare`, `beauty-spa`, `fitness-sports`, `pet-services`\n- Vehicles and home: `automotive`, `car-garages`, `home-services`, `real-estate`\n- Services: `professional-business-services`, `financial-services`, `technology`, `education`\n- Leisure: `entertainment`, `travel-tourism`", "name": "category", "in": "query" }, { "schema": { "type": "string", "description": "**Keep businesses carrying these tags.** Optional. Comma-separated tag slugs, e.g. `coffee` or\n`coffee,desserts`; up to 10.\n\n- With several tags a business must carry ALL of them.\n- Tag slugs come from `tags[].slug` on any business (e.g. `bakery-2` is the slug of the tag named\n `bakery`).\n- A tag no business carries simply matches nothing (an empty list).", "maxLength": 300 }, "required": false, "description": "**Keep businesses carrying these tags.** Optional. Comma-separated tag slugs, e.g. `coffee` or\n`coffee,desserts`; up to 10.\n\n- With several tags a business must carry ALL of them.\n- Tag slugs come from `tags[].slug` on any business (e.g. `bakery-2` is the slug of the tag named\n `bakery`).\n- A tag no business carries simply matches nothing (an empty list).", "name": "tags", "in": "query" }, { "schema": { "type": "string", "description": "**Result order.** Optional; omit it for relevance order (best match first).\n\n- `rating` — best reviewed first: highest `rating_average` (a whole-star average, rounded down —\n so a 4.8 business ranks with the 4s, after every 5), then most reviews; businesses without reviews\n come last\n- `newest` — the businesses most recently added to the directory first", "enum": [ "rating", "newest" ] }, "required": false, "description": "**Result order.** Optional; omit it for relevance order (best match first).\n\n- `rating` — best reviewed first: highest `rating_average` (a whole-star average, rounded down —\n so a 4.8 business ranks with the 4s, after every 5), then most reviews; businesses without reviews\n come last\n- `newest` — the businesses most recently added to the directory first", "name": "sort", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–1000.\n\nWalk pages until `businesses` comes back empty or `page` passes `total_pages`. A page past the end\nreturns an empty `businesses` array, not an error. Only the first 10,000 matches can be paged\n(`page` × `page_size` at most 10,000).", "minimum": 1, "maximum": 1000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–1000.\n\nWalk pages until `businesses` comes back empty or `page` passes `total_pages`. A page past the end\nreturns an empty `businesses` array, not an error. Only the first 10,000 matches can be paged\n(`page` × `page_size` at most 10,000).", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Businesses per page.** Default `20`; accepts 1–50. Larger values are rejected with 400.\n\n`total_pages` is computed for the page size you send, so keep it constant while walking pages.", "minimum": 1, "maximum": 50 }, "required": false, "description": "**Businesses per page.** Default `20`; accepts 1–50. Larger values are rejected with 400.\n\n`total_pages` is computed for the page size you send, so keep it constant while walking pages.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**Search the marketplace's business directory — restaurants, cafés, clinics, salons, gyms, shops,\ngarages and other local businesses in Kuwait.** These are directory entries, not classified sellers;\nfor dealers and offices that post listings use /business-profiles.\n\nReturns `query`, `category` (the slug you sent, or `null`), `tags`, `sort` (or `null`), `page`, `page_size`, `total`,\n`total_pages` and `businesses[]`, each with:\n\n- `business_id`, `slug`, `name` and `url` (the business's page on the directory website)\n- `category` (`slug`, `name`)\n- `about` — the business description as the directory shows it (for many businesses a generated\n sentence that quotes a rating from outside the directory — not the `rating_*` below)\n- `logo` and `cover_image` (image URLs; `cover_image` is `null` when the business has no usable cover)\n- `rating_average` and `rating_count` — the directory's own user reviews. Here `rating_average` is\n rounded DOWN to whole stars (an average of 4.8 shows as `4`); /directory-business-details gives the\n exact average. Most businesses have no reviews yet: `rating_count: 0` with `rating_average: null`\n- `tags[]` (`name`, `slug`) — cuisines, services and features; the slugs feed the `tags` filter\n- `working_hours[]` — `day` (lower case), `opens_at` and `closes_at` (`HH:MM`) exactly as the directory\n lists them, not normalised: `00:00`–`23:59` means open all day, some entries are written on a\n 12-hour clock without AM/PM (`12:00`–`11:30` = noon to 11:30 pm), and a `closes_at` earlier than\n `opens_at` is either such an entry or a close after midnight (`10:00`–`00:00`). A day that is missing\n has no hours listed.\n\nResults are in relevance order unless `sort` is sent. `total` is exact: a walk ends on it (the last page is partial, the\nnext one empty). Phone numbers and websites are not part of the search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": "cafe", "category": null, "tags": [], "sort": null, "page": 1, "page_size": 20, "total": 47, "total_pages": 3, "businesses": [ { "business_id": 536, "slug": "ojs-cafe", "name": "OJ’S Cafe", "url": "https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe", "category": { "slug": "restaurants-cafes", "name": "Restaurants & Cafes" }, "about": "OJ’S Cafe is a Cafe. They have been by the users, with a rating of 4.3.", "logo": "https://media.q84sale.com/directories/businesses/logos/1764152112_remote-upload", "cover_image": "https://media.q84sale.com/directories/businesses/covers/1767180006_business_image.jpg", "rating_average": null, "rating_count": 0, "tags": [ { "name": "bakery", "slug": "bakery-2" } ], "working_hours": [ { "day": "sunday", "opens_at": "09:00", "closes_at": "22:00" } ] }, { "business_id": 563, "slug": "wow-cafe", "name": "Wow Cafe", "url": "https://directory.q84sale.com/en/restaurants-cafes/wow-cafe", "category": { "slug": "restaurants-cafes", "name": "Restaurants & Cafes" }, "about": "Wow Cafe is a Cafe. They have been by the users, with a rating of 4.1.", "logo": "https://media.q84sale.com/directories/businesses/logos/1764152687_remote-upload", "cover_image": "https://media.q84sale.com/directories/businesses/covers/1764152689_remote-upload", "rating_average": null, "rating_count": 0, "tags": [ { "name": "bakery", "slug": "bakery-2" } ], "working_hours": [ { "day": "sunday", "opens_at": "00:00", "closes_at": "23:59" } ] } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/directory-business-details": { "get": { "tags": [ "Sellers" ], "operationId": "getDirectoryBusinessDetails", "description": "One business-directory entry by slug: phone numbers, website, amenities, opening hours, branches with coordinates and its star rating.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). Required; case-insensitive.\n\n- It is also the last part of the business's page address\n (`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`); the category is not needed.\n- An unknown slug is a **404**; anything that is not a slug (spaces, markup) is a **400**.", "example": "leila-min-lebnen" }, "required": true, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). Required; case-insensitive.\n\n- It is also the last part of the business's page address\n (`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`); the category is not needed.\n- An unknown slug is a **404**; anything that is not a slug (spaces, markup) is a **400**.", "name": "slug", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the business name, description and category name.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nOpening hours, phone numbers and amenities are the same in both languages; branch names\nand addresses are mostly written once, in the language the business entered them.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the business name, description and category name.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nOpening hours, phone numbers and amenities are the same in both languages; branch names\nand addresses are mostly written once, in the language the business entered them.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**One business from the marketplace's business directory, by slug — how to reach it, when it is open,\nwhere its branches are, and how it is rated.** The full entry behind each /directory-search result. Its photos and\nmenus are /directory-business-media; the reviews themselves, page by page, are /directory-business-reviews.\n\nReturns:\n\n- `language`, `business_id`, `slug`, `name`, `url` (its page on the directory website, in `lang`),\n `category` (`slug`, `name`), `about`, `logo`, `cover_image` (`null` when the business has no usable cover)\n- `phones` (as the business lists them, e.g. `+965 9449 8383`) and `website` (`null` when none)\n- `rating_average` and `rating_count` — the directory's own user reviews (`rating_average: null` when\n there are none) — and `rating_breakdown` (`[{stars, count}]`, 5 stars first). `rating_average` is the\n exact average of the breakdown to two decimals (e.g. 4.8), not the whole-star value /directory-search\n shows (4); if the breakdown cannot be read it is `null` and named in `partial_errors`\n- `view_count` — how often the business's directory page has been viewed (calling this adds no\n view). The directory's counter stops at 127, so `view_count_is_capped: true` means \"127 or more\"\n- `features` — the amenities and traits the directory lists, as keys such as `delivery`, `wi_fi`,\n `outdoor_seating`, `halal_food`, `wheelchair_accessible_entrance` (an empty list when none are listed);\n `price_range` (`budget`, `moderate`, …) and `google_place_id` (its Google Maps place id) when listed\n- `working_hours[]` — `day`, `opens_at`, `closes_at` exactly as the directory lists them, not\n normalised: `00:00`–`23:59` means open all day, some entries are written on a 12-hour clock without\n AM/PM (`12:00`–`11:30` = noon to 11:30 pm), and a `closes_at` earlier than `opens_at` is either such\n an entry or a close after midnight. A day that is missing has no hours listed.\n- `branches[]` — `branch_id`, `name`, `address`, `latitude`, `longitude`, `phone`, `is_main`\n- `listed_at` / `updated_at` — when the business was added to the directory and last edited, as ISO 8601\n times (`YYYY-MM-DDTHH:MM:SSZ`), as served\n- `partial_errors` — any part that could not be retrieved this time (`branches`,\n `rating_breakdown`, `rating_average`, `category_name`); that part is then `null`, never an empty list\n\nThe business's `tags` are on its /directory-search result, not here. `about` is the directory's text;\nfor many businesses it is a generated sentence quoting a rating from outside the directory, not\n`rating_average`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "language": "en", "business_id": 135, "slug": "leila-min-lebnen", "name": "Leila Min Lebnen", "url": "https://directory.q84sale.com/en/restaurants-cafes/leila-min-lebnen", "category": { "slug": "restaurants-cafes", "name": "Restaurants & Cafes" }, "about": "Leila Min Lebnan is a cornerstone of Lebanese cuisine, offering a taste of authentic Lebanese flavors. Indulge in an array of homemade dishes, beverages, and sweets, all prepared with fresh, locally s…", "logo": "https://media.q84sale.com/directories/businesses/logos/1764143567_remote-upload", "cover_image": null, "phones": [ "+965 9696 2668" ], "website": "https://leila-kw.com", "rating_average": 4.8, "rating_count": 5, "view_count": 127, "view_count_is_capped": true, "features": [ "breakfast", "brunch" ], "price_range": null, "google_place_id": null, "working_hours": [ { "day": "sunday", "opens_at": "09:00", "closes_at": "22:00" }, { "day": "monday", "opens_at": "09:00", "closes_at": "22:00" } ], "listed_at": "2025-11-26T07:53:30Z", "updated_at": "2026-01-28T08:02:03Z", "branches": [ { "branch_id": 1000217, "name": "Leila Min Lebnen", "address": "The Avenues Mall, Sheikh Zayed Bin Sultan Al Nahyan Rd, 13063, Kuwait", "latitude": 29.304360499999998, "longitude": 47.939054899999995, "phone": "+965 9696 2668", "is_main": true }, { "branch_id": 1000218, "name": "Leila Min Lebnen", "address": "Arabella Complex, Street 25, 25000, Kuwait", "latitude": 29.3028545, "longitude": 48.088014199999996, "phone": "+965 9800 2421", "is_main": false } ], "rating_breakdown": [ { "stars": 5, "count": 4 }, { "stars": 4, "count": 1 } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/directory-business-reviews": { "get": { "tags": [ "Sellers" ], "operationId": "listDirectoryBusinessReviews", "description": "The user reviews of one business-directory entry, newest first, page by page.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). It is also the last part of the business's page address\n(`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`). Required; case-insensitive.\n\n- An unknown slug is a **404**\n- Anything that is not a slug (spaces, markup) is a **400**", "example": "leila-min-lebnen" }, "required": true, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). It is also the last part of the business's page address\n(`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`). Required; case-insensitive.\n\n- An unknown slug is a **404**\n- Anything that is not a slug (spaces, markup) is a **400**", "name": "slug", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–1000.\n\n- Walk pages until `page` reaches `total_pages`\n- A page past the end returns an empty `reviews` array, not an error", "minimum": 1, "maximum": 1000 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–1000.\n\n- Walk pages until `page` reaches `total_pages`\n- A page past the end returns an empty `reviews` array, not an error", "name": "page", "in": "query" }, { "schema": { "type": "integer", "description": "**Reviews per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` is computed for the page size you send, so keep it constant while walking pages.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Reviews per page.** Default `20`; accepts 1–100. Larger values are rejected with 400.\n\n`total_pages` is computed for the page size you send, so keep it constant while walking pages.", "name": "page_size", "in": "query" } ], "responses": { "200": { "description": "**The public user reviews of one business-directory entry, newest first, one page at a time.** The\nstar summary (`rating_average`, `rating_count`, `rating_breakdown`) is on /directory-business-details.\n\nReturns:\n\n- `slug` — the business, in lower case\n- `page`, `page_size` — the page you asked for and its size\n- `total` — how many reviews the business has in all; `total_pages` — pages at this `page_size`\n (`0` when there are no reviews)\n- `reviews[]`, newest first:\n - `review_id`\n - `rating` — stars given, 1–5\n - `comment` — the review text as written (`null` when there is no text)\n - `reviewer_name` — the first name the reviewer shows publicly\n - `is_verified` — whether the directory marks the review as verified\n - `created_at`, `updated_at` — ISO 8601 times (`YYYY-MM-DDTHH:MM:SSZ`), as served\n\nA business without reviews answers `total: 0` with an empty `reviews` array. Reviews are shown as\nwritten, in whatever language the reviewer used.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "slug": "leila-min-lebnen", "page": 1, "page_size": 20, "total": 5, "total_pages": 1, "reviews": [ { "review_id": 83, "rating": 5, "comment": "Great", "reviewer_name": "Mohammed", "is_verified": false, "created_at": "2025-12-23T14:11:42Z", "updated_at": "2025-12-23T14:11:42Z" }, { "review_id": 48, "rating": 5, "comment": "Delicious Shawarma ❤️❤️❤️", "reviewer_name": "Sara", "is_verified": false, "created_at": "2025-12-22T23:40:07Z", "updated_at": "2025-12-22T23:41:22Z" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/directory-business-media": { "get": { "tags": [ "Sellers" ], "operationId": "listDirectoryBusinessMedia", "description": "The photos and menus of one business-directory entry, by slug.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). It is also the last part of the business's page address\n(`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`). Required; case-insensitive.\n\n- An unknown slug is a **404**\n- Anything that is not a slug (spaces, markup) is a **400**", "example": "leila-min-lebnen" }, "required": true, "description": "**The business — its directory slug**, exactly as /directory-search returns it in `slug`\n(e.g. `ojs-cafe`, `leila-min-lebnen`). It is also the last part of the business's page address\n(`https://directory.q84sale.com/en/restaurants-cafes/ojs-cafe` → `ojs-cafe`). Required; case-insensitive.\n\n- An unknown slug is a **404**\n- Anything that is not a slug (spaces, markup) is a **400**", "name": "slug", "in": "query" } ], "responses": { "200": { "description": "**The photos and menus of one business-directory entry, by slug.** The business itself (contacts,\nhours, branches, star ratings) is /directory-business-details; its reviews are /directory-business-reviews.\n\nReturns `slug` (the business, in lower case) and `media[]`, in the directory's own order, each with:\n\n- `media_id`\n- `category` — `gallery` (photos of the place, its products or dishes) or `menu` (the menu or price list)\n- `type` — what the address opens as:\n - `image` — a picture\n - `pdf` — a PDF document (menus only)\n - `page` — a saved web page, such as the business's link page, rather than a picture (menus only)\n- `url` — the address of the picture, document or page\n\nEach address is listed once, and only images and documents that load are listed — some photos the\ndirectory links from outside the marketplace no longer do. A business without photos or menus answers\nan empty `media` array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "slug": "leila-min-lebnen", "media": [ { "media_id": 3876, "type": "image", "category": "gallery", "url": "https://media.q84sale.com/directories/businesses/covers/1762761762_tmpehd8bmnx.jpg" }, { "media_id": 344, "type": "page", "category": "menu", "url": "https://media.q84sale.com/directories/businesses/menus/1764143622_remote-upload" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/sponsored-cards": { "get": { "tags": [ "Marketplace" ], "operationId": "listSponsoredCards", "description": "The sponsored banner cards shown in a category's search results.", "parameters": [ { "schema": { "type": "integer", "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.", "example": 2888, "minimum": 1, "maximum": 999999999 }, "required": true, "description": "**The category — a numeric 4Sale category id.** Required.\n\n- Find ids with /categories (browse the tree or search it by name), /autocomplete (`browse_category_id`)\n or `category.category_id` on any listing card.\n- An unknown id returns **404** with a message saying so.", "name": "category_id", "in": "query" } ], "responses": { "200": { "description": "**The sponsored banner cards shown inside a category's search results.** Who is advertising to buyers in\na category, and where the ad leads — lead-generation banners for finance, rentals, bookings and the like.\n\nReturns `category_id`, `total` and `cards[]`, each with `card_id`, `title`, `body`, `campaign_id`,\n`layout`, `image` plus `image_desktop`/`image_tablet`/`image_mobile`, `cta_text`,\n`cta_type` (`url`, `phone`, …), `cta_target`, `slot` and `display_order`.\n\n- Many categories have no card: `total: 0` with an empty `cards` list, which is a valid answer.\n- The same card (same `card_id`) can be returned for several categories, e.g. related property categories.\n- `title`, `body` and `cta_text` often carry the same text, as the advertiser entered it.\n- An unknown category id is a **404**.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "category_id": 2888, "total": 1, "cards": [ { "card_id": 41, "title": "Place your search lead gen banner", "body": "Place your search lead gen banner", "campaign_id": 30, "layout": "image_narrow", "image": "https://static.q84sale.com/images/cards/gGkLYWLNF2OW3QVsWzlZ7bfFfkEzAPPjtefEgpbI.png", "image_desktop": "https://static.q84sale.com/images/cards/pVVzUryRKenQ62CFfu4Q6260pM4RlTAQoBua4LWn.png", "image_tablet": "https://static.q84sale.com/images/cards/IAeyVOrKMQ1MFnqBv67UrEaW3wLEWZ4OEeYeSvYe.png", "image_mobile": "https://static.q84sale.com/images/cards/gGkLYWLNF2OW3QVsWzlZ7bfFfkEzAPPjtefEgpbI.png", "cta_text": "Place your search lead gen banner", "cta_type": "url", "cta_target": "https://www.q84sale.com/ar/booking/select-category", "slot": 1, "display_order": 1 } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/promo-codes": { "get": { "tags": [ "Marketplace" ], "operationId": "listPromoCodes", "description": "Promo codes currently valid for posting ads on the marketplace.", "responses": { "200": { "description": "**The promo codes currently valid for posting ads on the marketplace.** Useful for anyone budgeting ad\nspend on the marketplace, or tracking its pricing promotions.\n\nReturns `total` and `promo_codes[]`, each with `promo_code`, `discount_type` (`percent` or a fixed\namount), `discount_value`, `max_discount`, `description_en`/`description_ar` (what it applies to) and\n`expires_at`. Takes no parameters; an empty list means no public code is running.\n\n- `max_discount` is the most the code takes off, in KWD, or `null` when the code is uncapped (the\n marketplace stores \"no cap\" as `10000` KWD, far above any bundle price, and that is not a real cap).\n- `expires_at` is `YYYY-MM-DD HH:MM:SS`, as 4Sale serves it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "total": 1, "promo_codes": [ { "promo_code": "WELCOME25", "discount_type": "percent", "discount_value": 25, "max_discount": null, "description_en": "on basic bundle in all categories", "description_ar": "على الباقة الاساسية في جميع الأقسام", "expires_at": "2026-10-31 21:00:00" } ] } } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/home-sections": { "get": { "tags": [ "Marketplace" ], "operationId": "getHomeSections", "description": "What the home screen is promoting: trending categories, hero banners and sponsored cards.", "parameters": [ { "schema": { "type": "string", "description": "**Language of the whole home screen.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nEverything is localised: section titles and category names, the sponsored cards' titles and texts, and the\nbanners and card artwork themselves — Arabic serves different banner images (in a different order) and\ndifferent card artwork, not just translated text.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the whole home screen.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nEverything is localised: section titles and category names, the sponsored cards' titles and texts, and the\nbanners and card artwork themselves — Arabic serves different banner images (in a different order) and\ndifferent card artwork, not just translated text.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**What the marketplace's home screen is promoting right now.** Three parts:\n\n- `sections[]` — curated rails such as \"Trending Categories\", each with `items[]` of `category_id`,\n `name`, `slug`, `path_slug` (the category's web path) and `icon`;\n- `hero_banners[]` — the rotating top banners: `banner_id`, `image`, `target_type` (`deeplink` into the\n marketplace or an external `url`) and `target`;\n- `promo_cards[]` — sponsored cards with `title`, `image`, `cta_text` and `cta_target`.\n\nIf one part cannot be read (or comes back in an unexpected form) it is `null` with an entry in\n`partial_errors`; an empty `partial_errors` means all three were read. For the most-viewed listings\nsee /popular-listings; for trending search phrases see /trending-searches.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "language": "en", "sections": [ { "section_id": 37, "title": "Trending Categories", "content_type": "category", "items": [ { "category_id": 2897, "name": "Used Cars", "slug": "used-cars", "path_slug": "automotive/used-cars", "icon": "https://static.q84sale.com/images/cat_image/apr_2897.png", "display_order": 1 } ] } ], "hero_banners": [ { "banner_id": 66, "image": "https://static.q84sale.com/images/heroBanners/RGIrviDJMlF6fYcwBAbp9NOly2dLlvhx2KanAxx2.jpg", "target_type": "deeplink", "target": "https://www.q84sale.com/ar/businesses/dealerships/joon-al-kuwait-marine-774/all" }, { "banner_id": 38, "image": "https://static.q84sale.com/images/heroBanners/lbPOgOp1PjeXsyZYNDBebxZocEQIuMNaOAo7cVx6.png", "target_type": "deeplink", "target": "https://www.q84sale.com/ar/camping" } ], "promo_cards": [ { "card_id": 14, "title": "Calculate your Financing", "body": "Calculate your Financing", "campaign_id": 10, "layout": "image_narrow", "image": "https://static.q84sale.com/images/cards/CvYCEWYQe1SEJD83wEqNkMNLFeZmajsscj1xpKg5.jpg", "image_desktop": "https://static.q84sale.com/images/cards/o5WglhwgyViMHlU6g0n9piPiIx7Ju67DkKPm7dl3.jpg", "image_tablet": "https://static.q84sale.com/images/cards/rUPdM4msxYglxsoeEUhaiFy2AUimNQMTuICAv0Bp.jpg", "image_mobile": "https://static.q84sale.com/images/cards/CvYCEWYQe1SEJD83wEqNkMNLFeZmajsscj1xpKg5.jpg", "cta_text": "Calculate your Financing", "cta_type": "url", "cta_target": "https://kfh.com/auto/Home/Finance-calculator.html?utm_source=4sale&utm_medium=cpc&utm_campaign=4sale+ledgen&utm_id=KFH", "slot": 1, "display_order": 0 } ], "partial_errors": [] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/new-cars": { "get": { "tags": [ "Marketplace" ], "operationId": "searchNewCars", "description": "The new-car catalogue: models by brand with every trim and its price in KWD where the dealer publishes one.", "parameters": [ { "schema": { "type": "string", "minLength": 1, "maxLength": 200, "description": "**A brand, model or trim name, in English.** Required; 1–200 characters, e.g. `toyota` (every Toyota\nmodel), `prado`, `land cruiser`, `porsche`, `TX-L`.\n\n- Names are indexed in English only — an Arabic query finds nothing.\n- HTML tags and script-like text are refused with 400.", "example": "toyota" }, "required": true, "description": "**A brand, model or trim name, in English.** Required; 1–200 characters, e.g. `toyota` (every Toyota\nmodel), `prado`, `land cruiser`, `porsche`, `TX-L`.\n\n- Names are indexed in English only — an Arabic query finds nothing.\n- HTML tags and script-like text are refused with 400.", "name": "query", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–500. Every page holds 20 models (fixed).\n\nWalk pages until `models` comes back empty or `page` passes `total_pages`. A page past the end\nreturns an empty `models` array, not an error.", "minimum": 1, "maximum": 500 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–500. Every page holds 20 models (fixed).\n\nWalk pages until `models` comes back empty or `page` passes `total_pages`. A page past the end\nreturns an empty `models` array, not an error.", "name": "page", "in": "query" } ], "responses": { "200": { "description": "**The marketplace's new-car catalogue — current models from the official dealers, with every trim and\nits price in KWD.** The call for \"what does a new Prado cost?\" (`query=prado`) or \"every new Toyota\"\n(`query=toyota`).\n\nReturns `query`, `page`, `page_size` (always 20), `total`, `total_pages` and `models[]`, each with:\n\n- `model_id`, `slug`, `name`, `model_year`, `body_style` (`suv`, `sedan`, `sports`, `pickup`, `van`,\n `hatchback`, `minivan`, `crossover`, `coupe`, `wagon`) and `image`\n- `brand` (`brand_id`, `slug`, `name`, `logo`, `country_of_origin`, `manufacturing_countries`)\n- `price_from` / `price_to` + `currency` (KWD) — the cheapest and dearest trim that has a published\n price; `price_on_request` is `true` (and both prices `null`) when no trim has one\n- `engine`, `horsepower` (text as the catalogue writes it, e.g. `2.4L Turbo`, `353 - 739 hp`) and\n `fuel_types` (`petrol`, `hybrid`, `plugin_hybrid`, `electric`, `diesel`)\n- `trims_count` and `trims[]` — `trim_id`, `slug`, `name`, `badge` (e.g. `TX - L`), `price` (`null` =\n price on request) and `is_default`\n\nMatching is on the brand, model AND trim names, word by word and typo-tolerant:\n\n- a brand name returns all of that brand's models (`toyta` still finds the Toyotas);\n- a model name returns the models sharing a word with it (`land cruiser` → Land Cruiser and Urban Cruiser);\n- a trim name or badge finds the models that have that trim, word by word (`TX-L` → the Prado for its\n `TX - L` trim, plus models whose `EX-L` trims share the `L`);\n- it is not a body-style or feature search: `suv` returns the few models with a similar word in a model\n or trim name, not the catalogue's SUVs.\n\n`total` is exact.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "query": "toyota", "page": 1, "page_size": 20, "total": 29, "total_pages": 2, "models": [ { "model_id": 660, "slug": "toyota-hilux", "name": "Hilux", "brand": { "brand_id": 1998, "slug": "toyota", "name": "Toyota", "logo": "https://staging-raw-images.q84sale.com/raw/new_cars/anon/202607/d5ee52bd-6d33-4267-8d3c-8b4a450e75eb.svg", "country_of_origin": "Japan", "manufacturing_countries": [ "Japan" ] }, "model_year": 2026, "body_style": "pickup", "image": "https://staging-raw-images.q84sale.com/raw/new_cars/anon/202607/e3892626-77eb-44fe-9704-ce2c678053cd.webp", "price_from": 6900, "price_to": 8900, "currency": "KWD", "price_on_request": false, "engine": "2.7L / 4.0L V6", "horsepower": "164 - 235 hp", "fuel_types": [ "petrol" ], "trims_count": 10, "trims": [ { "trim_id": 856, "slug": "hilux-2-7l-sc-4x2-manual", "name": "Hilux 2.7L SC 4X2 MANUAL", "badge": "2.7L SC 4X2 MANUAL", "price": 6900, "is_default": false } ] }, { "model_id": 664, "slug": "toyota-hiace-v6", "name": "Hiace V6", "brand": { "brand_id": 1998, "slug": "toyota", "name": "Toyota", "logo": "https://staging-raw-images.q84sale.com/raw/new_cars/anon/202607/d5ee52bd-6d33-4267-8d3c-8b4a450e75eb.svg", "country_of_origin": "Japan", "manufacturing_countries": [ "Japan" ] }, "model_year": 2026, "body_style": "van", "image": "https://staging-raw-images.q84sale.com/raw/new_cars/anon/202607/e538bbe6-43a2-41db-b6db-7f385bcedbc9.jpg", "price_from": 6900, "price_to": 12312, "currency": "KWD", "price_on_request": false, "engine": "3.5L V6", "horsepower": "275 hp", "fuel_types": [ "petrol" ], "trims_count": 10, "trims": [ { "trim_id": 872, "slug": "hiace-v6-van-panel-3-seats-manual", "name": "Hiace V6 VAN - Panel (3 Seats) Manual", "badge": "VAN - Panel (3 Seats) Manual", "price": 6900, "is_default": false } ] } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/service-offers": { "get": { "tags": [ "Marketplace" ], "operationId": "listServiceOffers", "description": "Local service businesses advertising on the marketplace, with phone and WhatsApp numbers.", "parameters": [ { "schema": { "type": "integer", "description": "**Only the offers in this service category** (e.g. `24` AC, `11` Pack & Move, `1` Car Rental).\nOptional; omit it for every category.\n\n- Ids come from /service-categories — they are the service directory's own ids, not /categories ids.\n- An id /service-categories does not list (unknown or retired) is a **404**.", "minimum": 1, "maximum": 999999 }, "required": false, "description": "**Only the offers in this service category** (e.g. `24` AC, `11` Pack & Move, `1` Car Rental).\nOptional; omit it for every category.\n\n- Ids come from /service-categories — they are the service directory's own ids, not /categories ids.\n- An id /service-categories does not list (unknown or retired) is a **404**.", "name": "category_id", "in": "query" }, { "schema": { "type": "string", "description": "**Language of the offers.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nOffers are localised: each offer has its own Arabic business name and its own Arabic ad image, not\njust translated text.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the offers.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nOffers are localised: each offer has its own Arabic business name and its own Arabic ad image, not\njust translated text.", "name": "lang", "in": "query" }, { "schema": { "type": "integer", "description": "**Page number, 1-based.** Default `1`; accepts 1–100.\n\n- Each page holds up to `page_size` offers (set by the marketplace); `total` and `total_pages` say how\n many there are.\n- To collect them all, walk pages until `offers` comes back empty — a page past the end returns an\n empty `offers` array, not an error.", "minimum": 1, "maximum": 100 }, "required": false, "description": "**Page number, 1-based.** Default `1`; accepts 1–100.\n\n- Each page holds up to `page_size` offers (set by the marketplace); `total` and `total_pages` say how\n many there are.\n- To collect them all, walk pages until `offers` comes back empty — a page past the end returns an\n empty `offers` array, not an error.", "name": "page", "in": "query" } ], "responses": { "200": { "description": "**Local service businesses advertising on the marketplace, with their phone and WhatsApp numbers.** AC\nrepair, movers, cleaners, car services and more — a ready lead list of active advertisers.\n\nReturns `language`, `category_id` (the filter you sent, or `null`), `page`, `page_size`, `total`,\n`total_pages` and `offers[]`, each with `offer_id`, `title` (the business name), `image` (the ad\ncreative), `phone`, `whatsapp_phone`, `target_url` (the offer's link, as served; often `null`),\n`service_category_id` and `service_category_slug`\n(e.g. `ac`, `pack-move`). Filter by one category with `category_id` (the ids are on /service-categories).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "language": "en", "category_id": null, "page": 1, "page_size": 16, "total": 206, "total_pages": 13, "offers": [ { "offer_id": 7807, "title": "Top Look", "image": "https://q8ads.s3.eu-west-1.amazonaws.com/images/offers/1789028215520732377.jpg", "phone": "+96592256060", "whatsapp_phone": "+96592256060", "target_url": null, "service_category_id": 1, "service_category_slug": "car-rental" }, { "offer_id": 7705, "title": "Ahmad", "image": "https://q8ads.s3.eu-west-1.amazonaws.com/images/offers/1754899745549673904.jpg", "phone": "+96562222102", "whatsapp_phone": "+96562222102", "target_url": null, "service_category_id": 30, "service_category_slug": "motors" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "404": { "description": "The named item does not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/service-categories": { "get": { "tags": [ "Marketplace" ], "operationId": "listServiceCategories", "description": "The service directory's categories — the ids /service-offers filters by.", "parameters": [ { "schema": { "type": "string", "description": "**Language of the category names.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nIds, slugs and icons are the same in both languages.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the category names.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nIds, slugs and icons are the same in both languages.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The categories of the marketplace's service directory** — AC, Pack & Move, Car Rental, Cleaning,\nPainter and the rest. These are the ids /service-offers filters by with `category_id` (they are the\nservice directory's own ids, not /categories ids).\n\nReturns `language`, `total`, `all_offer_pages` (how many pages /service-offers has without a filter)\nand `categories[]`, each with `service_category_id`, `name` (in the requested language), `slug`,\n`icon` (`null` for a category without one) and `offer_pages` (how many pages /service-offers has for\nthat category). The whole list comes in one response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "language": "en", "total": 17, "all_offer_pages": 13, "categories": [ { "service_category_id": 2, "name": "Property", "slug": "property", "icon": "https://q8ads.s3.eu-west-1.amazonaws.com/images/categories/14610689181079903059.jpg", "offer_pages": 1 }, { "service_category_id": 1, "name": "Car Rental", "slug": "car-rental", "icon": "https://q8ads.s3.eu-west-1.amazonaws.com/images/categories/1461068786679366042.jpg", "offer_pages": 4 } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } }, "/blog-articles": { "get": { "tags": [ "Marketplace" ], "operationId": "listBlogArticles", "description": "The handful of editorial blog posts the marketplace's app features.", "parameters": [ { "schema": { "type": "string", "description": "**Language of the article titles and summaries.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nThe article `url` opens the same post on the web in either case.", "enum": [ "en", "ar" ], "default": "en" }, "required": false, "description": "**Language of the article titles and summaries.** Default `en`.\n\n- `en` — English\n- `ar` — Arabic\n\nThe article `url` opens the same post on the web in either case.", "name": "lang", "in": "query" } ], "responses": { "200": { "description": "**The blog articles the marketplace's app features** — buying and selling guides and marketplace tips.\n\nReturns `language`, `total` and `articles[]`, each with `article_id`, `title`, `summary`, `image`,\n`url` and `published_on` (day-month-year). Takes only the language.\n\nThis is the app's blog feed — the short, fixed selection of posts the app shows (a handful, not the\nwhole blog archive on the website). It is returned in one piece; there are no further pages.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleSuccessResponseSchema" }, "example": { "success": true, "data": { "language": "en", "total": 3, "articles": [ { "article_id": 23, "title": "Tips for Creating an Effective 4Sale Listing", "summary": "When it comes to creating a listing on 4Sale, there are many factors that come into play. There are many factors that can affect the performance of a listing.", "image": "https://static.q84sale.com/images/cms_images/original/neL8HT7ujA2u.png", "url": "https://www.q84sale.com/blog/tips-for-creating-an-effective-4sale-listing/", "published_on": "28-07-2021" }, { "article_id": 24, "title": "Reasons to Sell your Used Car on 4Sale / Q8Car", "summary": "Selling used cars —and vehicles, in general, can be difficult, especially if you’re selling not a mainstream model that’s in high demand. You need to find the right buyer who will give you the highest…", "image": "https://static.q84sale.com/images/cms_images/original/Xu8Z8QRV2Z62.png", "url": "https://www.q84sale.com/blog/reasons-to-sell-your-used-car-on-4sale-q8car/", "published_on": "28-07-2021" } ] } } } } }, "400": { "description": "Bad request — the message says what to change", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } }, "503": { "description": "Temporarily busy — retry shortly", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FourSaleErrorResponseSchema" } } } } } } } }, "servers": [ { "url": "https://rapid-api-tools-worker.pictureperfect.workers.dev/happy-endpoint/api/tools/4sale-api", "description": "Base URL" } ] }