Listing feed

RFX does not own its public listings (level 1). A licensed provider supplies them through the API below. Until the provider's API is ready, a mock implements the same contract, so switching means changing one address and one key.

Connection

Base address	`CATALOG_URL` in RFX
Authentication	`Authorization: Bearer <key>`, the key in `CATALOG_API_KEY`. Calls without it get 401
Format	JSON. Every path starts with `/v1`; a change that breaks a caller gets a new version

Endpoints

Method and path	Returns
`GET /v1/markets`	The markets (categories) with `id`, `name`, `source`, `updated_at`, `vendor_count`
`GET /v1/markets/{id}/vendors`	One page of a market's listings and `next_cursor` (null on the last page). Query: `limit` 1 to 500, `cursor`, `updated_since`
`GET /v1/vendors/{id}`	One listing
`GET /health`	No key. Whether the API can serve

A listing

{
  "id": "hubspot",
  "vendor": "HubSpot",
  "product": "HubSpot Sales Hub",
  "website": "https://www.hubspot.com",
  "rating": null,
  "ratings_count": null,
  "rating_verified": false,
  "source_url": "https://provider.example/vendors/hubspot",
  "market_id": "crm",
  "updated_at": "2026-11-10T08:00:00Z"
}

id is stable and unique across markets. A vendor that claims its listing keeps it as its address.
website is the domain a vendor must prove control of before RFX accepts it as the company. Without it, RFX uses the website the vendor gives when it claims, a weaker check.
Ratings only where the licence allows RFX to show them. Review text is never wanted.

How RFX reads it

At start, every page of every market. Only when all were read does RFX replace the listings it holds, so a failure half-way changes nothing.
Again every hour (CATALOG_REFRESH_MINUTES, 0 turns it off). If the provider cannot be reached, RFX keeps what it has and logs a warning.
A listing that leaves the feed leaves level 1. A vendor that had claimed it keeps its account, documents and deals.

At 10,000 listings and 500 per page, a refresh is about 20 calls. The full contract, with error codes and limits, is docs/CATALOG_API.md in the repository.