> ## Documentation Index
> Fetch the complete documentation index at: https://lopiv2-invenicum-25.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Locations API

> Manage location hierarchies and organizational structure

## Overview

The Locations API enables management of hierarchical location structures within containers. Locations can be nested to create organizational hierarchies, allowing for precise tracking of where inventory items are stored.

## Endpoints

### Get Locations

Retrieves all locations associated with a specific container.

```http theme={null}
GET /containers/{containerId}/locations
```

#### Path Parameters

**containerId** `integer` *required*

The ID of the container whose locations to retrieve

#### Response

**data** `Location[]`

Array of location objects

**Location Object**

**id** `integer`

Unique identifier for the location

**name** `string`

Display name of the location

**description** `string`

Optional description of the location

**containerId** `integer`

ID of the parent container

**parentId** `integer`

ID of the parent location (null for root locations)

**children** `Location[]`

Nested array of child locations (hierarchical structure)

#### Example Request

```javascript theme={null}
const response = await fetch('/containers/42/locations', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

const { data } = await response.json();
```

#### Example Response

```json theme={null}
{
  "data": [
    {
      "id": 1,
      "name": "Warehouse A",
      "description": "Main warehouse facility",
      "containerId": 42,
      "parentId": null,
      "children": [
        {
          "id": 2,
          "name": "Shelf 1",
          "description": "First shelf in warehouse",
          "containerId": 42,
          "parentId": 1,
          "children": []
        }
      ]
    }
  ]
}
```

#### Error Responses

**401** `error`

Unauthorized - Authentication required or token invalid

**404** `error`

Container not found

***

### Create Location

Creates a new location within a container.

```http theme={null}
POST /locations
```

#### Request Body

**container\_id** `integer` *required*

ID of the container to create the location in

**name** `string` *required*

Name of the location

**description** `string`

Optional description of the location

**parent\_id** `integer`

ID of the parent location (omit for root-level location)

#### Response

**data** `Location`

The newly created location object

#### Example Request

```javascript theme={null}
const response = await fetch('/locations', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    container_id: 42,
    name: 'Warehouse B',
    description: 'Secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();
```

#### Example Response

```json theme={null}
{
  "data": {
    "id": 5,
    "name": "Warehouse B",
    "description": "Secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}
```

#### Error Responses

**201** `success`

Location created successfully

**401** `error`

Unauthorized - Invalid or missing authentication token

**400** `error`

Bad request - Invalid parent\_id or missing required fields

***

### Update Location

Updates an existing location's details.

```http theme={null}
PATCH /locations/{locationId}
```

#### Path Parameters

**locationId** `integer` *required*

The ID of the location to update

#### Request Body

**name** `string` *required*

Updated name of the location

**description** `string`

Updated description

**parent\_id** `integer`

Updated parent location ID (use null to make it a root location)

#### Response

**data** `Location`

The updated location object

#### Example Request

```javascript theme={null}
const response = await fetch('/locations/5', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Warehouse B - Expanded',
    description: 'Expanded secondary storage facility',
    parent_id: null
  })
});

const { data } = await response.json();
```

#### Example Response

```json theme={null}
{
  "data": {
    "id": 5,
    "name": "Warehouse B - Expanded",
    "description": "Expanded secondary storage facility",
    "containerId": 42,
    "parentId": null
  }
}
```

#### Error Responses

**200** `success`

Location updated successfully

**401** `error`

Unauthorized - Authentication required

**404** `error`

Location not found

**400** `error`

Bad request - Invalid parent\_id (would create circular hierarchy)

***

### Delete Location

Deletes a location from the system.

```http theme={null}
DELETE /locations/{locationId}
```

#### Path Parameters

**locationId** `integer` *required*

The ID of the location to delete

#### Response

Returns status code 204 (No Content) or 200 (OK) on successful deletion.

#### Example Request

```javascript theme={null}
const response = await fetch('/locations/5', {
  method: 'DELETE',
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

if (response.status === 204) {
  console.log('Location deleted successfully');
}
```

#### Error Responses

**204** `success`

Location deleted successfully (no content returned)

**200** `success`

Location deleted successfully

**401** `error`

Unauthorized - Authentication required

**404** `error`

Location not found

**409** `error`

Conflict - Cannot delete location with child locations or assigned items

***

## Business Logic Notes

### Hierarchical Structure

* Locations support unlimited nesting depth through the `parent_id` field
* The `children` array is populated recursively when retrieving locations
* Root-level locations have `parent_id` set to `null`

### Deletion Rules

* Locations with child locations must have children removed first
* Locations with assigned inventory items cannot be deleted until items are reassigned
* Consider implementing soft deletes for audit trail purposes

### Performance Considerations

* The `children` array is not included in `toJson()` to prevent circular serialization issues
* For deep hierarchies, consider implementing pagination or lazy loading of child locations
* The `getLocationsCount()` method fetches all locations and returns the count - consider server-side counting for large datasets

### Access Control

* All location operations require valid JWT authentication
* Users can only access locations within containers they have permission to view
* Container ownership determines location management permissions


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.