---
title: "Provider catalog for villa-tablet browse overlay + featured carousel. Returns validated providers ordered best-first for the given coordinates (nearest first when coords provided, rating-desc fallback when absent)"
method: GET
path: "/providers"
tags: ["WellFred public API"]
---

# Provider catalog for villa-tablet browse overlay + featured carousel. Returns validated providers ordered best-first for the given coordinates (nearest first when coords provided, rating-desc fallback when absent)

`GET /providers`

## Request

- Base URL: `https://app.wellfred.com/api/agent`
- URL: `https://app.wellfred.com/api/agent/providers`
- Auth: none declared

Response: { providers: [ { id, name, category, subcategory?, description?,
                            imageUrl?, priceFrom?, distanceKm?, rating? } ] }
Only id/name/category are guaranteed; the rest are null when the schema
has no data for a row. Defaults to 25 providers; limit accepts up to 500.

category/subcategory are the slugs of the provider's first custom-service
category and subcategory (Str::slug(name_en)); category is "other" when no
services exist, subcategory is null when the first service has none. The
subcategory helps distinguish services because the top-level taxonomy
is coarse (private chefs share the "house-home" category with cleaners).
priceFrom is the lowest getBasePrice() across all the provider's services.
rating is the 0–5 star normalised fred_score (same formula as searchServices).
distanceKm is haversine distance from the supplied lat/lng; null when absent.

## Query parameters

- `lat` number, nullable
- `lng` number, nullable
- `limit` integer, nullable
- `page` integer, nullable
- `categoryUuid` string, uuid, nullable
- `subcategoryUuid` string, uuid, nullable
- `catalogServiceUuid` string, uuid, nullable
- `selection` 'all' | 'recommended' | 'featured' | 'null', nullable
- `serviceIds[]` string[]

## Response `200`

- object
  - `success` boolean, required
  - `message` string, required
  - `providers` string, required
  - `meta` object, required
    - `page` 1, required
    - `limit` object, nullable, required
    - `total` string, required
    - `hasMore` boolean, required

## Other responses

- `422`: Validation error

---

[API](https://skmtc.dev/wellfred/apis/wellfred-api.md) · [All operations](https://skmtc.dev/wellfred/apis/wellfred-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wellfred/apis/wellfred-api/revisions/5a6665793917?raw)