# Categories — Eto API

> The Etsy taxonomy and the properties each category allows.

Base URL `https://eto.tools/api/v1/`. Every request carries the `X-Eto-API-Key` header. Part of the [Eto API reference](https://eto.tools/dev/docs/).

## Endpoints in this category

- [GET /api/v1/categories](https://eto.tools/dev/docs/categories/categories.md): Get product categories
- [GET /api/v1/categories/{category_id}/properties](https://eto.tools/dev/docs/categories/category-properties.md): Get category properties
- [GET /api/v1/buyer-categories](https://eto.tools/dev/docs/categories/buyer-categories.md): Get buyer categories
- [GET /api/v1/buyer-categories/{category_id}/properties](https://eto.tools/dev/docs/categories/buyer-category-properties.md): Get buyer category properties

## GET /api/v1/categories

Get product categories

- Operation ID: `categories`
- Slug: `categories`
- Category: Categories
- Authentication: API key only. Reads public marketplace data, so no store needs to be connected.
- HTML: https://eto.tools/dev/docs/#ep-categories
- Markdown: https://eto.tools/dev/docs/categories/categories.md

Get the full product category tree (e.g. Jewelry, Clothing, Home Decor). Use category IDs when creating listings to place them in the right section. Etsy docs: "Seller Taxonomy Nodes".

Proxied to the Etsy API at `/v3/application/seller-taxonomy/nodes`. Fields Etsy returns are passed through untouched.

### Parameters

None. Send the request with only the API key header.

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/categories"
```

```python
import requests

url = "https://eto.tools/api/v1/categories"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/categories";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/seller-taxonomy/nodes` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## GET /api/v1/categories/{category_id}/properties

Get category properties

- Operation ID: `category_properties`
- Slug: `category-properties`
- Category: Categories
- Authentication: API key only. Reads public marketplace data, so no store needs to be connected.
- HTML: https://eto.tools/dev/docs/#ep-category-properties
- Markdown: https://eto.tools/dev/docs/categories/category-properties.md

Get the required and optional fields for a category — like size, color, or material options that buyers can filter by. Etsy docs: "Taxonomy Node Properties".

Proxied to the Etsy API at `/v3/application/seller-taxonomy/nodes/{category_id}/properties`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category_id` | path | `integer` | yes | The category ID (from /categories) |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/categories/1/properties"
```

```python
import requests

url = "https://eto.tools/api/v1/categories/1/properties"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/categories/1/properties";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/seller-taxonomy/nodes/{category_id}/properties` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## GET /api/v1/buyer-categories

Get buyer categories

- Operation ID: `buyer_categories`
- Slug: `buyer-categories`
- Category: Categories
- Authentication: API key only. Reads public marketplace data, so no store needs to be connected.
- HTML: https://eto.tools/dev/docs/#ep-buyer-categories
- Markdown: https://eto.tools/dev/docs/categories/buyer-categories.md

Get the category tree from a buyer's perspective — how shoppers browse Etsy. Etsy docs: "Buyer Taxonomy Nodes".

Proxied to the Etsy API at `/v3/application/buyer-taxonomy/nodes`. Fields Etsy returns are passed through untouched.

### Parameters

None. Send the request with only the API key header.

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/buyer-categories"
```

```python
import requests

url = "https://eto.tools/api/v1/buyer-categories"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/buyer-categories";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/buyer-taxonomy/nodes` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.


## GET /api/v1/buyer-categories/{category_id}/properties

Get buyer category properties

- Operation ID: `buyer_category_properties`
- Slug: `buyer-category-properties`
- Category: Categories
- Authentication: API key only. Reads public marketplace data, so no store needs to be connected.
- HTML: https://eto.tools/dev/docs/#ep-buyer-category-properties
- Markdown: https://eto.tools/dev/docs/categories/buyer-category-properties.md

Get filterable properties for a buyer category. Etsy docs: "Buyer Taxonomy Properties".

Proxied to the Etsy API at `/v3/application/buyer-taxonomy/nodes/{category_id}/properties`. Fields Etsy returns are passed through untouched.

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `category_id` | path | `integer` | yes | The buyer category ID |

### Request

```bash
curl -H "X-Eto-API-Key: eto_your_key" "https://eto.tools/api/v1/buyer-categories/1/properties"
```

```python
import requests

url = "https://eto.tools/api/v1/buyer-categories/1/properties"
headers = {"X-Eto-API-Key": "eto_your_key"}

response = requests.get(url, headers=headers, timeout=120)
response.raise_for_status()
print(response.json())
```

```javascript
const url = "https://eto.tools/api/v1/buyer-categories/1/properties";

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-Eto-API-Key": "eto_your_key",
  },
});
if (!response.ok) throw new Error(`Eto API ${response.status}`);
const data = await response.json();
```

### Response

`application/json`, passed through from Etsy’s `/v3/application/buyer-taxonomy/nodes/{category_id}/properties` verbatim. The field-by-field data model is in the [v2 preview reference](https://eto.tools/eto-dev-api-v2/), which documents these same routes alongside the whole Etsy schema.

### Errors

Failures answer with the shared error body described in the Errors section: `{"error": {"code", "status", "message", "hint", "docs"}}`. Branch on `code`, not on the message.