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

PublicApiKey

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

HTTPcURLJavaScriptPython

GET /api/v1/public/warehouses HTTP/1.1
x-api-key: YOUR_API_KEY
Accept: */*

{
  "data": [
    {
      "id": "text",
      "warehouse_code": "text",
      "name": "text",
      "description": "text",
      "status": "active",
      "purpose": "production",
      "storage_type": "default",
      "division_count": 1,
      "created_at": "2026-07-10T16:14:01.576Z",
      "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": {}
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "lastPage": 1,
    "currentPage": 1,
    "perPage": 1,
    "prev": 1,
    "next": 1
  }
}

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

PublicApiKey

x-api-keystringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

application/json

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

HTTPcURLJavaScriptPython

POST /api/v1/public/warehouses HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 293

{
  "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": {}
    }
  ],
  "location": "text"
}

{
  "id": "text",
  "warehouse_code": "text",
  "name": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "created_at": "2026-07-10T16:14:01.576Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": {}
    }
  ],
  "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

PublicApiKey

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

HTTPcURLJavaScriptPython

GET /api/v1/public/warehouses/check-uniqueness?field=name&value=text HTTP/1.1
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

PublicApiKey

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}

HTTPcURLJavaScriptPython

GET /api/v1/public/warehouses/{id} HTTP/1.1
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-07-10T16:14:01.576Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": {}
    }
  ],
  "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

PublicApiKey

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}

HTTPcURLJavaScriptPython

DELETE /api/v1/public/warehouses/{id} HTTP/1.1
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

PublicApiKey

x-api-keystringRequired

Path parameters

idstringRequired

Header parameters

x-tenant-idstring · uuidOptional

Tenant id (uuid v4)

Body

application/json

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}

HTTPcURLJavaScriptPython

PATCH /api/v1/public/warehouses/{id} HTTP/1.1
x-api-key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 314

{
  "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": {}
    }
  ],
  "location": "text"
}

{
  "id": "text",
  "warehouse_code": "text",
  "name": "text",
  "description": "text",
  "status": "active",
  "purpose": "production",
  "storage_type": "default",
  "created_at": "2026-07-10T16:14:01.576Z",
  "divisions": [
    {
      "id": "text",
      "division_code": "text",
      "name": "text"
    }
  ],
  "custom_column_values": [
    {
      "id": "text",
      "custom_column_id": "text",
      "value": {}
    }
  ],
  "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"
        }
      ]
    }
  ]
}