Read category names and slugs
Fetch the live Flipns category hierarchy from /v1/categories or get_categories to filter public listing searches with valid slugs and handle aliases.
Use GET /v1/categories to read the current category tree and its selectable slugs:
curl --fail-with-body 'https://api.flipns.com/v1/categories'The response is a flat categories array. Each row has a slug, name, depth and isLeaf. Rows with a parent also have parentSlug. emoji and iconKey are optional presentation hints; clients can ignore them. iconKey is a plain-text key for category artwork.
Use a returned slug as the category filter on GET /v1/listings/search. The same category slugs are available to MCP clients through get_categories and can be passed as category to search_listings. Read the current tree instead of hard-coding category names or assuming a particular number of categories.
curl --fail-with-body --get 'https://api.flipns.com/v1/listings/search' \
--data-urlencode 'q=phone' \
--data-urlencode 'category=mobile-phones'Category filters identify a category and its descendants. During the taxonomy transition, some older one-to-one slugs remain accepted as filter aliases, but they are not returned by /v1/categories. Older broad slugs that split across multiple destinations, including mobiles-electronics and sports-books-hobbies, cannot identify one filter and return UNKNOWN_CATEGORY. Refresh /v1/categories and let the person choose from the current options. Category organization can change over time, so preserve listing URLs for saved listings instead of trying to reconstruct their category from an old label.
The API response is the machine-readable source for integrations. People can also browse categories on Flipns.