# Categories and catalogue terms

> The category tree and catalogue terms such as brands and designers.

The category tree and catalogue terms such as brands and designers. Generated from the [OpenAPI spec](https://dev.mongrl.com/openapi.json). Each endpoint says which key it needs; see [Authentication](https://dev.mongrl.com/guides/authentication.md).

| Method | Path | What it does |
|---|---|---|
| GET | [`/v1/catalog-terms`](#list-catalogue-terms-of-a-kind) | List catalogue terms of a kind |
| GET | [`/v1/catalog-terms/{kind}/{slug}`](#get-a-catalogue-term-by-its-slug) | Get a catalogue term by its slug |
| GET | [`/v1/categories`](#list-the-category-tree) | List the category tree |

## List catalogue terms of a kind

`GET /v1/catalog-terms` · operation `listCatalogTerms`

E.g. all brands, ordered by name, a page at a time; `q` filters by the start of the name.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `kind` * | query | string | One of the marketplace's term kinds |
| `q` | query | string | Only names starting with this. max 200 chars |
| `limit` | query | integer | ≥ 1; ≤ 200; default `50` |
| `cursor` | query | string | next_cursor from the previous page |
| `locale` | query | string | Language for descriptions |
| `in_use` | query | boolean | Only terms that listings on sale use, all at once (no paging, q ignored), each with listing_count |

**Responses:** `200` [PublicTermPageBody](#publictermpagebody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Get a catalogue term by its slug

`GET /v1/catalog-terms/{kind}/{slug}` · operation `getCatalogTerm`

E.g. a designer's page: /v1/catalog-terms/designer/poul-henningsen.

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `kind` * | path | string |  |
| `slug` * | path | string |  |
| `locale` | query | string | Language for the description |

**Responses:** `200` [TermBody](#termbody) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## List the category tree

`GET /v1/categories` · operation `listCategories`

All categories with parent ids, in one language (falling back to the default).

**Auth:** a secret or publishable key (`Authorization: Bearer sk_…` or `pk_…`)

**Parameters**

| Name | In | Type | Notes |
|---|---|---|---|
| `locale` | query | string | Language for names; the marketplace's default when omitted |

**Responses:** `200` [ListCategoriesResponse](#listcategoriesresponse) · `default` [a problem](https://dev.mongrl.com/reference/conventions.md#errors)

## Schemas

Fields marked * are always present in responses and required in requests.

### PublicTermPageBody

| Field | Type | Notes |
|---|---|---|
| `items` * | [TermBody](#termbody)[] |  |
| `next_cursor` | string |  |

### TermBody

| Field | Type | Notes |
|---|---|---|
| `description` | string |  |
| `id` * | string |  |
| `kind` * | string |  |
| `listing_count` | integer | Listings on sale with this term (with in_use) |
| `name` * | string |  |
| `slug` * | string |  |

### ListCategoriesResponse

| Field | Type | Notes |
|---|---|---|
| `items` * | [CategoryBody](#categorybody)[] |  |

### CategoryBody

| Field | Type | Notes |
|---|---|---|
| `id` * | string |  |
| `name` * | string |  |
| `parent_id` | string |  |
| `position` * | integer |  |
| `slug` * | string |  |