Warehouses

List warehouses

get

Returns every warehouse on the tenant — across all statuses (active / inactive / archived) — paginated.

Query

search (optional) — substring (ILIKE) match on name OR warehouse_code, case-insensitive.
skip / take (optional) — standard offset pagination; defaults to skip = 0, take = 20.

The response items intentionally omit the heavyweight inventory-page extras (custom-column values, location detail, creator info). Use GET /custom-columns/:id to load detail when you need everything.

Authorizations

x-api-keystringRequired

Query parameters

searchstring · max: 255Optional

Substring (ILIKE) match on name OR warehouse_code, case-insensitive.

skipnumberOptionalDefault: 0

takenumber · min: 1OptionalDefault: 20

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/warehouses

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

{
  "meta": {
    "total": 1,
    "lastPage": 1,
    "currentPage": 1,
    "perPage": 1,
    "prev": 1,
    "next": 1
  },
  "data": [
    {
      "id": "text",
      "warehouse_code": "text",
      "name": "text",
      "description": "text",
      "status": "active",
      "purpose": "production",
      "storage_type": "default",
      "division_count": 1,
      "created_at": "2026-01-01T00:00:00.000Z",
      "created_by": {
        "id": "text",
        "first_name": "text",
        "last_name": "text",
        "avatar_id": "text"
      },
      "location": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "display_name": "text"
      },
      "custom_column_values": [
        {
          "custom_column_id": "text",
          "value": "text"
        }
      ]
    }
  ]
}

Create warehouse

post

Creates a new warehouse on the tenant.

Notes

name must be unique within the tenant.
warehouse_code is auto-generated when omitted (digits-only sequential id). Custom codes max 18 chars, must be unique.
purpose is required and immutable in practice. wip is reserved for the system-managed in-progress warehouse and cannot be created here.
status defaults to active; archived is allowed on create but soft-locks the row from non-admin edits in the FE.
storage_type defaults to default (no divisions). divisions is ignored unless storage_type is overridden.
location is a free-form display name (max 500 chars). The server finds-or-creates a warehouse_locations row by that name and links the warehouse to it. latitude / longitude are left null when the row is created through this endpoint (public API doesn't carry geo coords).

`custom_column_values` — what to pass

Each entry is { custom_column_id: uuid, value: ... }. The value's shape must match the referenced column's column_type (server validates the combination — bad shapes are rejected with 400):

text — string. Length bounds enforced by the column's config.{min_chars, max_chars}.
```
{ "custom_column_id": "uuid", "value": "Free-form note" }
```
number — integer or float. config.number_type = "integer" rejects decimals.
```
{ "custom_column_id": "uuid", "value": 42 }
```
date_time — ISO-8601 string. Shape depends on config.time_type (date_time / date_only / time_only).
```
{ "custom_column_id": "uuid", "value": "2026-06-18T12:00:00Z" }
```
people — entity uuid (user / department / position id, matching config.assignee_type), or an array for multi.
```
{ "custom_column_id": "uuid", "value": "user-uuid" }
```

boolean — true or false.

{ "custom_column_id": "uuid", "value": true }

choice — choice_option_id for choice_type = "single", or an array of ids for "multi".
```
{ "custom_column_id": "uuid", "value": "choice-option-uuid" }
```

On update, full-reconcile semantics apply: listed columns are upserted, columns with stored values that are absent from the request are deleted.

Authorizations

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestring · max: 255Required

warehouse_codestring · min: 1 · max: 18Optional

Optional override of the auto-generated warehouse code. Max 18 chars; must be unique within the tenant.

descriptionstring · max: 1000Optional

statusstring · enumOptionalDefault: activePossible values:

purposestring · enumRequiredPossible values:

storage_typestring · enumOptionalDefault: defaultPossible values:

locationstring · min: 1 · max: 500Optional

Free-form location name. The server finds-or-creates a warehouse_locations row by display_name; lat/lng default to null when the row is created here.

Responses

201Success

application/json

idstringRequired

warehouse_codestringRequired

Auto-generated digits-only sequential code by default; admins may set free-form text up to 18 chars.

namestringRequired

descriptionstring · nullableRequired

statusstring · enumRequiredPossible values:

purposestring · enumRequiredPossible values:

storage_typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

429

Returned when the rate limit is exceeded

post/api/v1/public/warehouses

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

{
  "name": "text",
  "warehouse_code": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "divisions": [
    {
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "custom_column_id": "123e4567-e89b-12d3-a456-426614174000",
      "value": "text"
    }
  ],
  "location": "text"
}

{
  "id": "text",
  "warehouse_code": "text",
  "name": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "created_at": "2026-01-01T00:00:00.000Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": "text"
    }
  ],
  "location": {
    "id": "text",
    "place_id": "text",
    "display_name": "text",
    "latitude": 1,
    "longitude": 1
  },
  "inventory_columns": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "column_type": "text",
      "config": {
        "min_chars": 1,
        "max_chars": 1
      },
      "choice_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "label": "text",
          "position": 1
        }
      ],
      "people_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "entity_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ]
}

Check whether a warehouse name or warehouse_code is available

get

Returns { is_available: true } when no warehouse already owns the supplied value, false otherwise.

Query

field — one of name or warehouse_code.
value — candidate string to test (max 255 chars; the value is not length-validated against the field's create rules — that happens at create / update time).

Authorizations

x-api-keystringRequired

Query parameters

fieldstring · enumRequiredPossible values:

valuestring · max: 255Required

Candidate value to check; the BE validates availability only — length/character rules are enforced by the regular create/update DTOs at submit time.

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

is_availablebooleanRequired

true → value is free to use; false → another warehouse already owns it.

429

Returned when the rate limit is exceeded

get/api/v1/public/warehouses/check-uniqueness

GET /api/v1/public/warehouses/check-uniqueness?field=name&value=text HTTP/1.1
Host: api-stage.hesh.tech
x-api-key: YOUR_API_KEY
Accept: */*

{
  "is_available": true
}

Get warehouse by id

get

Returns the full warehouse record, including divisions, custom_column_values (raw stored values), and inventory_columns (definitions for every column referenced by this warehouse — join inventory_columns[].id with custom_column_values[].custom_column_id on the client).

location is currently always null for warehouses created through the public API.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

idstringRequired

warehouse_codestringRequired

Auto-generated digits-only sequential code by default; admins may set free-form text up to 18 chars.

namestringRequired

descriptionstring · nullableRequired

statusstring · enumRequiredPossible values:

purposestring · enumRequiredPossible values:

storage_typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

429

Returned when the rate limit is exceeded

get/api/v1/public/warehouses/{id}

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

{
  "id": "text",
  "warehouse_code": "text",
  "name": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "created_at": "2026-01-01T00:00:00.000Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": "text"
    }
  ],
  "location": {
    "id": "text",
    "place_id": "text",
    "display_name": "text",
    "latitude": 1,
    "longitude": 1
  },
  "inventory_columns": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "column_type": "text",
      "config": {
        "min_chars": 1,
        "max_chars": 1
      },
      "choice_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "label": "text",
          "position": 1
        }
      ],
      "people_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "entity_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ]
}

Hard-delete warehouse

delete

Hard-deletes the warehouse. Rejected if the warehouse has any related operations (production workflows). The wip warehouse cannot be 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/warehouses/{id}

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

No content

Update warehouse

patch

Updates a warehouse. Any field not provided is left unchanged.

Notes

warehouse_code and storage_type are locked once the warehouse has related operations (production workflows, etc.).
description accepts null to clear an existing value.
divisions and custom_column_values use full-reconcile semantics — listed rows are upserted, existing rows absent from the request are deleted. Pass an empty array to clear everything.
location (string) finds-or-creates a warehouse_locations row by display name and links it. Pass null to clear the existing link; omit the field to leave it unchanged.

`custom_column_values` — what to pass

Each entry is { custom_column_id: uuid, value: ... }. The value's shape must match the referenced column's column_type (server validates the combination — bad shapes are rejected with 400):

text — string. Length bounds enforced by the column's config.{min_chars, max_chars}.
```
{ "custom_column_id": "uuid", "value": "Free-form note" }
```
number — integer or float. config.number_type = "integer" rejects decimals.
```
{ "custom_column_id": "uuid", "value": 42 }
```
date_time — ISO-8601 string. Shape depends on config.time_type (date_time / date_only / time_only).
```
{ "custom_column_id": "uuid", "value": "2026-06-18T12:00:00Z" }
```
people — entity uuid (user / department / position id, matching config.assignee_type), or an array for multi.
```
{ "custom_column_id": "uuid", "value": "user-uuid" }
```

boolean — true or false.

{ "custom_column_id": "uuid", "value": true }

choice — choice_option_id for choice_type = "single", or an array of ids for "multi".
```
{ "custom_column_id": "uuid", "value": "choice-option-uuid" }
```

On update, full-reconcile semantics apply: listed columns are upserted, columns with stored values that are absent from the request are deleted.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

namestring · max: 255Optional

warehouse_codestring · min: 1 · max: 18Optional

Locked once the warehouse has related operations.

descriptionstring · max: 1000 · nullableOptional

Send null to clear the existing description.

statusstring · enumOptionalPossible values:

storage_typestring · enumOptional

Locked once the warehouse has related operations.

Possible values:

locationstring · min: 1 · max: 500 · nullableOptional

Pass a non-empty string to find-or-create and link, null to clear the existing link, omit to leave unchanged.

Responses

200Success

application/json

idstringRequired

warehouse_codestringRequired

Auto-generated digits-only sequential code by default; admins may set free-form text up to 18 chars.

namestringRequired

descriptionstring · nullableRequired

statusstring · enumRequiredPossible values:

purposestring · enumRequiredPossible values:

storage_typestring · enumRequiredPossible values:

created_atstring · date-timeRequired

429

Returned when the rate limit is exceeded

patch/api/v1/public/warehouses/{id}

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

{
  "name": "text",
  "warehouse_code": "text",
  "description": "text",
  "status": "active",
  "storage_type": "default",
  "divisions": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "custom_column_id": "123e4567-e89b-12d3-a456-426614174000",
      "value": "text"
    }
  ],
  "location": "text"
}

{
  "id": "text",
  "warehouse_code": "text",
  "name": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "created_at": "2026-01-01T00:00:00.000Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": "text"
    }
  ],
  "location": {
    "id": "text",
    "place_id": "text",
    "display_name": "text",
    "latitude": 1,
    "longitude": 1
  },
  "inventory_columns": [
    {
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "name": "text",
      "column_type": "text",
      "config": {
        "min_chars": 1,
        "max_chars": 1
      },
      "choice_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "label": "text",
          "position": 1
        }
      ],
      "people_options": [
        {
          "id": "123e4567-e89b-12d3-a456-426614174000",
          "entity_id": "123e4567-e89b-12d3-a456-426614174000"
        }
      ]
    }
  ]
}

List divisions on a warehouse

get

Returns every non-deleted division belonging to the supplied warehouse. Divisions are the addressable sub-locations within a non-default-storage warehouse (bins, cells, shelves — depends on storage_type).

Response

Flat array of { id, name, division_code, warehouse_id } — small enough that no pagination is required. Warehouses whose storage_type is default return an empty array.

Notes

The division_code is the value clients pass on inventory-add / move endpoints under division_id — via the id field. division_code is the human-facing label.

Authorizations

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Responses

200Success

application/json

idstring · uuidRequired

namestringRequired

division_codestringRequired

Short code for the division; unique within the warehouse.

warehouse_idstring · uuidRequired

429

Returned when the rate limit is exceeded

get/api/v1/public/warehouses/{id}/divisions

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

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

PreviousUsers

NextSecurity

Last updated 12 days ago

List warehouses

Query

Create warehouse

Notes

custom_column_values — what to pass

Check whether a warehouse name or warehouse_code is available

Query

Get warehouse by id

Hard-delete warehouse

Update warehouse

Notes

custom_column_values — what to pass

List divisions on a warehouse

Response

Notes

`custom_column_values` — what to pass

`custom_column_values` — what to pass