Product Categories

List product categories

get

Returns categories in the tenant.

Query

parent_id (optional) — when provided, returns children of that node. When omitted, returns roots.
tree (optional, default false) — when true, returns the full subtree rooted at parent_id (or all roots + descendants when omitted) nested via children[]. Pagination is ignored in this mode.
search (optional) — case-insensitive substring match on name.
page / limit (optional) — page-based pagination for the flat mode. Defaults: page = 1, limit = 25, max limit = 100.
include_deleted (optional, default false) — include soft-deleted categories in the response.

Each item includes id, name, parent_id, path (root→parent breadcrumbs), and is_active (computed as deleted_at IS NULL).

Authorizations

x-api-keystringRequired

Query parameters

parent_idstring · uuidOptional

Return children of this parent id. Omit to return roots.

treebooleanOptional

When true, return the full subtree as a nested tree.

Default: false

searchstring · max: 100Optional

Case-insensitive substring match on name.

pagenumber · min: 1OptionalDefault: 1

limitnumber · min: 1 · max: 100OptionalDefault: 25

include_deletedbooleanOptionalDefault: false

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

objectOptional

429

Returned when the rate limit is exceeded

get/api/v1/public/product-categories

GET /api/v1/public/product-categories HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{}

Create category

post

Creates a new category.

Notes

name is required (1..255 chars).
parent_id — when omitted, creates a root category. When provided, the parent must exist and be active (soft-deleted parents → 404).
name must be unique (case-insensitive) among active siblings under the same parent — 409 on collision.

Tag storage is deliberately not yet modelled — do not send tags; the tag endpoints are stubbed.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestring · min: 1 · max: 255Required

parent_idstring · uuidOptional

Parent id. Omit for root category.

Responses

201Success

application/json

idstringRequired

namestringRequired

parent_idstring · nullableRequired

is_activebooleanRequired

Computed from deleted_at IS NULL.

created_atstring · nullableRequired

429

Returned when the rate limit is exceeded

post/api/v1/public/product-categories

POST /api/v1/public/product-categories HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 66

{
  "name": "text",
  "parent_id": "123e4567-e89b-12d3-a456-426614174000"
}

{
  "id": "text",
  "name": "text",
  "parent_id": "text",
  "path": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "is_active": true,
  "created_at": "text"
}

Get category by id

get

Returns a single category with optional expansions.

Query

include (optional, CSV) — one or more of products, children.
products_page, products_limit — pagination for the products include (defaults 1 / 25, max 100).

Soft-deleted categories return 404 unless the caller can prove the id exists — call GET /?include_deleted=true to find them.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Query parameters

includestringOptional

Comma-separated list. Supported: products, children.

products_pagenumber · min: 1Optional

Page for the products include.

Default: 1

products_limitnumber · min: 1 · max: 100Optional

Page size for the products include.

Default: 25

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

idstringRequired

namestringRequired

parent_idstring · nullableRequired

is_activebooleanRequired

Computed from deleted_at IS NULL.

created_atstring · nullableRequired

429

Returned when the rate limit is exceeded

get/api/v1/public/product-categories/{id}

GET /api/v1/public/product-categories/{id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "parent_id": "text",
  "path": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "is_active": true,
  "created_at": "text",
  "products": {
    "data": [
      {
        "id": "text",
        "name": "text"
      }
    ],
    "meta": {
      "total": 1,
      "lastPage": 1,
      "currentPage": 1,
      "perPage": 1,
      "prev": 1,
      "next": 1
    }
  },
  "children": [
    {
      "id": "text",
      "name": "text",
      "parent_id": "text",
      "path": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "name": "text"
        }
      ],
      "is_active": true,
      "created_at": "text"
    }
  ]
}

Soft-delete category

delete

Marks the category as deleted. Non-cascading.

Rejected with 409 when

The category has any non-deleted children.
The category has any product_meta referencing it.
The category is already soft-deleted.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

204Success

No content

429

Returned when the rate limit is exceeded

delete/api/v1/public/product-categories/{id}

DELETE /api/v1/public/product-categories/{id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

No content

Update category

patch

Updates a category. All fields are optional.

Rules

name — must not collide with an active sibling under the current or new parent (409).
parent_id — pass null to promote to root. Cannot equal :id and cannot equal any descendant of :id (would create a cycle → 400). New parent must be active.
is_active — true restores a soft-deleted category, false soft-deletes it. Rejected (409) if the current state already matches.
Rejected with 409 if the record is soft-deleted and you send a non-is_active field — restore it first.
Successful parent_id moves recompute the materialized path for the moved node and all its descendants.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestring · min: 1 · max: 255Optional

parent_idstring · nullableOptional

New parent. Pass null to promote to root. Rejected if it would create a cycle.

is_activebooleanOptional

true → restore soft-deleted, false → soft-delete. Rejected if state is already what you set.

Responses

200Success

application/json

idstringRequired

namestringRequired

parent_idstring · nullableRequired

is_activebooleanRequired

Computed from deleted_at IS NULL.

created_atstring · nullableRequired

429

Returned when the rate limit is exceeded

patch/api/v1/public/product-categories/{id}

PATCH /api/v1/public/product-categories/{id} HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 51

{
  "name": "text",
  "parent_id": "text",
  "is_active": true
}

{
  "id": "text",
  "name": "text",
  "parent_id": "text",
  "path": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "is_active": true,
  "created_at": "text"
}

Restore soft-deleted category

post

Clears deleted_at and deleted_by. Returns 409 if the category is not currently deleted.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

201Success

application/json

idstringRequired

namestringRequired

parent_idstring · nullableRequired

is_activebooleanRequired

Computed from deleted_at IS NULL.

created_atstring · nullableRequired

429

Returned when the rate limit is exceeded

post/api/v1/public/product-categories/{id}/restore

POST /api/v1/public/product-categories/{id}/restore HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "id": "text",
  "name": "text",
  "parent_id": "text",
  "path": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ],
  "is_active": true,
  "created_at": "text"
}

Get breadcrumbs for a category

get

Returns { path: [{ id, name }] } — the root→parent breadcrumb chain for the given category. Empty array for root categories.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

429

Returned when the rate limit is exceeded

get/api/v1/public/product-categories/{id}/path

GET /api/v1/public/product-categories/{id}/path HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "path": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text"
    }
  ]
}

PreviousPosition Types NextProduction Item Tags

Last updated 24 days ago