# Categories

Product categories and their safety requirements.

## Endpoints

-   [GET `/v2/categories`](https://public-api.dapi.digital/docs/reference/categories.md#list_categories)
-   [GET `/v2/categories/{id}`](https://public-api.dapi.digital/docs/reference/categories.md#get_category)

## The category object

A product category. Categories form a two-level tree and decide which safety requirements a product must meet.

### Attributes

-   `id` (string): Unique identifier of the category, prefixed with `cat_`. Treat it as an opaque string: store it and compare it, never parse it.
-   `object` (string): Names the type of this object. Always `category`.
-   `name` (string): Display name.
-   `slug` (string): URL-safe name, unique across categories.
-   `description` (string or null): Longer explanation of what belongs here, when provided.
-   `parent` (object or null): The top-level category this one belongs to. Null for a top-level category. Products may use either level.
    -   `id` (string): Unique identifier of the category, prefixed with `cat_`. Treat it as an opaque string: store it and compare it, never parse it.
    -   `object` (string): Names the type of this object. Always `category`.
    -   `name` (string): Display name of the category.
-   `compliance` (CategoryCompliance): EU/UK product safety (GPSR) requirements for products in this category, with everything inherited from the parent category already applied.
    -   `risk_level` (string or null): GPSR risk level of products in this category. Null when none is set.
        
        Possible values: `low`, `medium`, `high`, `critical`.
        
    -   `ce_marking_required` (boolean): Whether products in this category need CE marking.
    -   `age_restriction` (string or null): Free-text age restriction, for example `0-36 months` or `18+`. Null when none applies.
    -   `safety_warnings_required` (boolean): Whether the product page must show safety warnings for this category.
    -   `safety_flags` (array of string): Typical hazards for the category, in snake\_case, for example `choking_hazard`.
    -   `mandatory_warnings` (array of string): Exact warning sentences that are shown on the product page of every product in this category.
    -   `required_documents` (array of RequiredDocument): Documents a product in this category must provide. Whether a missing document currently blocks publishing is reported on the product, in `publishing.blockers`.
        -   `key` (string): Stable identifier of the requirement. Use it to say which requirement an uploaded compliance document satisfies.
        -   `name` (string): Name of the document, as shown to sellers.

**The category object**

```json
{
  "id": "cat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
  "object": "category",
  "name": "Action Figures & Dolls",
  "slug": "toys-and-games--action-figures-and-dolls",
  "description": null,
  "parent": {
    "id": "cat_9Qa1GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
    "object": "category",
    "name": "Toys & Games"
  },
  "compliance": {
    "risk_level": "high",
    "ce_marking_required": false,
    "age_restriction": null,
    "safety_warnings_required": true,
    "safety_flags": [
      "choking_hazard",
      "age_restriction"
    ],
    "mandatory_warnings": [
      "Warning. Not suitable for children under 36 months. Small parts. Choking hazard."
    ],
    "required_documents": [
      {
        "key": "material-toxicity-assessment",
        "name": "Material Toxicity Assessment"
      },
      {
        "key": "technical-file-and-risk-assessment",
        "name": "Technical File & Risk Assessment"
      }
    ]
  }
}
```

## List product categories

GET `/v2/categories`

Public: no API key needed.

- **Credentials**: None: the endpoint is public.

- **For**: Designers and Integrators

- **Operation id**: `list_categories`

Lists every product category as a flat list; each subcategory points at its `parent`. Public: no credentials needed. Use it to pick a category for a product and to see the safety requirements that come with it.

### Query parameters

-   `parent` (string): Only return the subcategories of this top-level category.
-   `limit` (integer): How many results per page, from 1 to 100.
    
    Range 1 to 100. Defaults to 20.
    
-   `cursor` (string): Where to continue from: the `next_cursor` of the previous page. Omit for the first page.

### Returns 200 OK

A page of categories, in display order.

Response attributes (CategoryList):

-   `object` (string): Names the type of this object. Always `list`.
-   `data` (array of Category): The page of results.
    
    Described in [the category object](https://public-api.dapi.digital/docs/reference/categories.md#category_object).
    
-   `has_more` (boolean): True when more results exist after this page. Fetch them by passing `next_cursor` as `cursor`.
-   `next_cursor` (string or null): Opaque cursor for the next page, or null on the last page. Pass it back unchanged as `cursor`.

### Responses

-   `200`: A page of categories, in display order.
-   `400`: The request is invalid. `details.errors` lists each problem (`validation_failed`), or an `expand[]` path is unknown (`invalid_expand`).
-   `429`: Too many requests (`rate_limited`): the limit is 120 per minute per IP address. Wait for the number of seconds in the `Retry-After` header, then retry; `details` has `limit`, `window_seconds`, `reset_at` and `retry_after_seconds`.

Errors use [the error object](https://public-api.dapi.digital/docs/guides/errors.md#error-object).

**Request**

```bash
curl "https://public-api.dapi.digital/v2/categories"
```

**Response 200**

```json
{
  "object": "list",
  "data": [
    {
      "id": "cat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
      "object": "category",
      "name": "Action Figures & Dolls",
      "slug": "toys-and-games--action-figures-and-dolls",
      "description": null,
      "parent": {
        "id": "cat_9Qa1GSqKoZFrD72H5Os0rc7HV9XP6eQJu",
        "object": "category",
        "name": "Toys & Games"
      },
      "compliance": {
        "risk_level": "high",
        "ce_marking_required": false,
        "age_restriction": null,
        "safety_warnings_required": true,
        "safety_flags": [
          "choking_hazard",
          "age_restriction"
        ],
        "mandatory_warnings": [
          "Warning. Not suitable for children under 36 months. Small parts. Choking hazard."
        ],
        "required_documents": [
          {
            "key": "material-toxicity-assessment",
            "name": "Material Toxicity Assessment"
          },
          {
            "key": "technical-file-and-risk-assessment",
            "name": "Technical File & Risk Assessment"
          }
        ]
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Get a product category

GET `/v2/categories/{id}`

Public: no API key needed.

- **Credentials**: None: the endpoint is public.

- **For**: Designers and Integrators

- **Operation id**: `get_category`

Returns one category with its resolved safety requirements. Public: no credentials needed.

### Path parameters

-   `id` (string, required): Unique identifier of the category, prefixed with `cat_`. Treat it as an opaque string: store it and compare it, never parse it.

### Returns 200 OK

The category. Returns [the category object](https://public-api.dapi.digital/docs/reference/categories.md#category_object).

### Responses

-   `200`: The category.
-   `404`: No category has this id (`category_not_found`).
-   `429`: Too many requests (`rate_limited`): the limit is 120 per minute per IP address. Wait for the number of seconds in the `Retry-After` header, then retry; `details` has `limit`, `window_seconds`, `reset_at` and `retry_after_seconds`.

Errors use [the error object](https://public-api.dapi.digital/docs/guides/errors.md#error-object).

**Request**

```bash
curl "https://public-api.dapi.digital/v2/categories/cat_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu"
```

---

3DAPI API Docs. This page on the web: https://public-api.dapi.digital/docs/reference/categories. Index of every page: https://public-api.dapi.digital/docs/llms.txt.