For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
get/api/v1/public/warehouses

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" }
  • booleantrue or false.

    { "custom_column_id": "uuid", "value": true }
  • choicechoice_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
post/api/v1/public/warehouses

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.

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

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

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

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

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" }
  • booleantrue or false.

    { "custom_column_id": "uuid", "value": true }
  • choicechoice_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
patch/api/v1/public/warehouses/{id}

Last updated