Return the currently authenticated OLX user (GET /me). Also confirms that login and token caching are working.

Force a fresh login with the configured credentials and report success. Useful for diagnosing authentication problems.

Retrieve a single listing by its id (GET /listings/:id). Returns the full listing object: title, price, location, status, images and owner details.

List a user's listings, filtered by state (GET /users/:user/listings and its finished/inactive/expired/hidden variants). Paginated. Use state: active for the public/visible listings. The user is a username for active listings and a user id for the other states, matching the OLX API.

Full-text search across OLX listings (GET /search). Public — works without credentials. Combine a text query with filters (category, brand, city, price range, condition, recency). Returns a compact summary per listing plus pagination meta and category aggregations. Set raw: true for the full untrimmed payload. Use extra_params for advanced/rare query keys such as attribute filters (attr, attr_encoded) or custom sorting.

Return all top-level categories (GET /categories).

Return the child categories of a category (GET /categories/:id). Use this to walk the category tree down to a leaf before creating a listing.

Return a single category with detailed properties such as base_listing_price and top_category status (GET /category/:id).

Return the attributes for a category (GET /categories/:id/attributes), including input_type, options and whether each is required. These define the attributes you can set when creating a listing in this category.

Return the brands available for a category (GET /categories/:id/brands).

Return the models for a brand within a category (GET /categories/:id/brands/:brand_id/models).

Suggest categories for a listing title/keyword (GET /categories/suggest?keyword=). Handy for auto-selecting a category when creating a listing.

Find categories matching a name, with their hierarchical path (GET /categories/find?name=).

Return all countries with id, name and code (GET /countries).

Return all cities with their cantons (GET /cities).

Return a single city with coordinates, zip_code, country_id and canton_id (GET /cities/:id). Use the id as city_id when creating a listing.

Return country states with their cantons (GET /country-states).

Return the cities within a canton (GET /cantons/:id/cities).

Create a new listing in DRAFT status (POST /listings). Only title is required. The listing is NOT visible until you call publish_listing. Resolve category_id via the category tools and city_id via the location tools first.

Update fields on an existing listing (PUT /listings/:id). Provide only the fields you want to change alongside the listing id.

Activate a DRAFT listing so it becomes visible in search (POST /listings/:id/publish).

Bump a listing's rank by refreshing its timestamp (PUT /listings/:id/refresh). Subject to quota — check get_refresh_limits. May consume a paid refresh once the free quota is exhausted.

Return refresh quota: free_limit, free_count, paid_count, listing_count (GET /listing/refresh/limits).

Return per-category listing limits (cars, real-estate, other) with current counts (GET /listing-limits).

Mark a listing as completed/sold (POST /listings/:id/finish). This ends the active listing; it moves to the user's finished listings.

Hide a listing from search; it stays visible on the user profile (POST /listings/:id/hide).

Restore a hidden listing's visibility (POST /listings/:id/unhide).

PERMANENTLY delete a listing (DELETE /listings/:id). This is irreversible — confirm with the user before calling.

Attach image(s) to a listing (POST /listings/:id/image-upload). Provide either image_url (the API fetches it) and/or an images array of image URLs. Returns the created image objects with their ids and sizes.

Remove one image from a listing (POST /listings/:id/image-delete).

Set a listing's primary/cover image (POST /listings/:id/image-main).

Get a price quote for sponsoring a listing (GET /listings/:id/sponsore/price). Read-only — ALWAYS call this and show the quote to the user before sponsor_listing.

Purchase sponsorship/promotion for a listing (POST /listings/:id/sponsore). THIS SPENDS OLX CREDITS. Call get_sponsor_price first, present the total to the user, and only proceed after explicit confirmation.

Set a temporary discounted price on a listing (POST /listings/:id/discount). This changes the live price shown to buyers for the given period. Confirm with the user first.

End an active discount early and restore the original price (POST /listings/:id/discount/finish).