# Read category names and slugs (/developers/categories)

Use `GET /v1/categories` to read the current category tree and its selectable slugs:

```bash
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.

```bash
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](https://flipns.com/categories).

[REST quickstart](/developers/rest-quickstart) · [MCP guide](/developers/mcp) · [OpenAPI contract](https://api.flipns.com/openapi.json)
