### Items / ItemList - Get item definitions

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns item definition data.

```lua
-- Get all items
local items = exports.ox_inventory:Items()
for name, data in pairs(items) do
    print(name, data.label, data.weight)
end

-- Get specific item
local burger = exports.ox_inventory:Items('burger')
print(burger.label, burger.weight, burger.stack)
```

--------------------------------

### Register Buy Item Hook

Source: https://context7.com/communityox/ox_inventory/llms.txt

Intercept item buying events. This example simply prints information about the purchase.

```lua
-- Hook for buying items
exports.ox_inventory:registerHook('buyItem', function(payload)
    print('Buying', payload.count, 'x', payload.itemName, 'from', payload.shopType)
end)
```

--------------------------------

### Register Open Inventory Hook

Source: https://context7.com/communityox/ox_inventory/llms.txt

Intercept inventory opening events. This example prints information about the opening event and shows how to prevent opening by returning false.

```lua
-- Hook for opening inventory
exports.ox_inventory:registerHook('openInventory', function(payload)
    print('Player', payload.source, 'opening', payload.inventoryType, payload.inventoryId)
    -- Return false to prevent opening
end, {
    inventoryFilter = { '^stash', '^trunk' } -- Pattern matching
})
```

--------------------------------

### GetInventory - Get full inventory data

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves the complete inventory data, including items, current weight, and maximum weight capacity.

```APIDOC
## GetInventory - Get full inventory data

### Description
Returns complete inventory data including items, weight, and configuration.

### Method
GET (conceptual)

### Endpoint
exports.ox_inventory:GetInventory(source)

### Parameters
#### Path Parameters
- **source** (string | number) - Required - The identifier for the inventory (player source or inventory name).

### Request Example
```lua
-- Get player inventory
local inv = exports.ox_inventory:GetInventory(source)
print('Weight:', inv.weight, '/', inv.maxWeight)
print('Slots:', inv.slots)

-- Get stash inventory
local stash = exports.ox_inventory:GetInventory('police_locker')
for slot, item in pairs(stash.items) do
    print(item.name, item.count)
end
```

### Response
#### Success Response (200)
- **inventory** (object) - An object containing inventory details.
  - **weight** (number) - Current weight of the inventory.
  - **maxWeight** (number) - Maximum weight capacity of the inventory.
  - **slots** (number) - Total number of slots in the inventory.
  - **items** (object) - An object where keys are slot numbers and values are item objects.

#### Response Example
```json
{
  "weight": 1500,
  "maxWeight": 50000,
  "slots": 30,
  "items": {
    "1": {
      "name": "burger",
      "count": 2,
      "metadata": {}
    },
    "5": {
      "name": "water",
      "count": 1,
      "metadata": {}
    }
  }
}
```
```

--------------------------------

### Items / ItemList - Get item definitions

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns item definition data.

```APIDOC
## Items / ItemList - Get item definitions

### Description
Returns item definition data.

### Method
`exports.ox_inventory:Items([itemName])`

### Parameters
#### Path Parameters
- **itemName** (string) - Optional - The name of a specific item to retrieve data for.

### Response
#### Success Response (200)
- **items** (table) - A table containing all item definitions if no `itemName` is provided. Each item is a table with properties like `label`, `weight`, `stack`, etc.
- **itemData** (table) - The definition data for the specified `itemName`.

### Request Example
```lua
-- Get all items
local items = exports.ox_inventory:Items()
for name, data in pairs(items) do
    print(name, data.label, data.weight)
end

-- Get specific item
local burger = exports.ox_inventory:Items('burger')
print(burger.label, burger.weight, burger.stack)
```
```

--------------------------------

### GetItem - Get item data from inventory

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns item data including current count from a player's inventory.

```lua
-- Get item with count
local item = exports.ox_inventory:GetItem(source, 'burger')
print(item.name, item.label, item.count) -- 'burger', 'Burger', 5

-- Get item with metadata filter
local item = exports.ox_inventory:GetItem(source, 'water', { type = 'sparkling' })

-- Get only the count (more efficient)
local count = exports.ox_inventory:GetItem(source, 'burger', nil, true)
print('Burger count:', count) -- 5
```

--------------------------------

### Register Using Item Hook

Source: https://context7.com/communityox/ox_inventory/llms.txt

Intercept item usage events. This example prevents the 'lockpick' item from being used if a condition is not met.

```lua
-- Hook for using items
exports.ox_inventory:registerHook('usingItem', function(payload)
    if payload.item.name == 'lockpick' then
        if not canUseLockpick(payload.source) then
            return false -- Cancel item use
        end
    end
end)
```

--------------------------------

### Register Item Creation Hook

Source: https://context7.com/communityox/ox_inventory/llms.txt

Intercept item creation events to modify metadata. This example modifies the 'burger' item's metadata.

```lua
-- Hook for item creation (modify metadata)
exports.ox_inventory:registerHook('createItem', function(payload)
    if payload.item.name == 'burger' then
        payload.metadata.cooked = os.time()
        return payload.metadata
    end
end, {
    print = true, -- Debug printing
    itemFilter = { burger = true }
})
```

--------------------------------

### GetInventoryItems - Get inventory items only

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves only the items from an inventory, excluding weight and slot count information.

```APIDOC
## GetInventoryItems - Get inventory items only

### Description
Returns only the items table from an inventory.

### Method
GET (conceptual)

### Endpoint
exports.ox_inventory:GetInventoryItems(source, owner_identifier)

### Parameters
#### Path Parameters
- **source** (string | number) - Required - The identifier for the inventory (player source or inventory name).
- **owner_identifier** (string) - Optional - Used for shared inventories to specify an owner.

### Request Example
```lua
local items = exports.ox_inventory:GetInventoryItems(source)
for slot, item in pairs(items) do
    print(slot, item.name, item.count)
end

-- Get stash items with owner
local items = exports.ox_inventory:GetInventoryItems('personal_stash', 'char1:abc123')
```

### Response
#### Success Response (200)
- **items** (object) - An object where keys are slot numbers and values are item objects.

#### Response Example
```json
{
  "1": {
    "name": "burger",
    "count": 2,
    "metadata": {}
  },
  "5": {
    "name": "water",
    "count": 1,
    "metadata": {}
  }
}
```
```

--------------------------------

### GetItemCount - Get total count of an item

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the total count of matching items in an inventory.

```lua
-- Get total burger count
local count = exports.ox_inventory:GetItemCount(source, 'burger')

-- Get count with metadata filter
local count = exports.ox_inventory:GetItemCount(source, 'water', { type = 'sparkling' }, true)
-- strict = true means exact metadata match, false allows partial matching
```

--------------------------------

### GetCurrentWeapon - Get player's current weapon

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the currently equipped weapon data.

```lua
local weapon = exports.ox_inventory:GetCurrentWeapon(source)
if weapon then
    print('Weapon:', weapon.name)
    print('Ammo:', weapon.metadata.ammo)
    print('Durability:', weapon.metadata.durability)
    print('Serial:', weapon.metadata.serial)
end
```

--------------------------------

### GetCurrentWeapon - Get player's current weapon

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the currently equipped weapon data.

```APIDOC
## GetCurrentWeapon - Get player's current weapon

### Description
Returns the currently equipped weapon data.

### Method
`exports.ox_inventory:GetCurrentWeapon(source)`

### Parameters
#### Path Parameters
- **source** (number) - Required - The player's source ID.

### Response
#### Success Response (200)
- **weapon** (table) - The weapon data, including name, metadata (ammo, durability, serial), etc. Returns nil if no weapon is equipped.

### Response Example
```lua
local weapon = exports.ox_inventory:GetCurrentWeapon(source)
if weapon then
    print('Weapon:', weapon.name)
    print('Ammo:', weapon.metadata.ammo)
    print('Durability:', weapon.metadata.durability)
    print('Serial:', weapon.metadata.serial)
end
```
```

--------------------------------

### Get Full Inventory Data

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves the complete inventory details, including all items, current weight, and maximum weight capacity. Can be used for both player inventories and specific stash types.

```lua
-- Get player inventory
local inv = exports.ox_inventory:GetInventory(source)
print('Weight:', inv.weight, '/', inv.maxWeight)
print('Slots:', inv.slots)

-- Get stash inventory
local stash = exports.ox_inventory:GetInventory('police_locker')
for slot, item in pairs(stash.items) do
    print(item.name, item.count)
end
```

--------------------------------

### Register Swap Items Hook

Source: https://context7.com/communityox/ox_inventory/llms.txt

Intercept item swap events to control transfers. This example blocks weapons from being transferred to non-police players.

```lua
-- Hook for swapping items (can block transfers)
local hookId = exports.ox_inventory:registerHook('swapItems', function(payload) 
    -- Block transferring weapons to non-police players
    if payload.toType == 'player' and payload.fromSlot.name:find('WEAPON_') then
        if not hasPoliceJob(payload.toInventory) then
            return false -- Block the transfer
        end
    end
end, {
    itemFilter = {
        WEAPON_PISTOL = true,
        WEAPON_CARBINERIFLE = true
    },
    typeFilter = {
        player = true
    }
})
```

--------------------------------

### Get Specific Slot Data

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves item data from a specific inventory slot. Use when you know the exact slot number.

```lua
-- Get item in slot 1
local slot = exports.ox_inventory:GetSlot(source, 1)
if slot then
    print(slot.name, slot.count, slot.metadata.durability)
end
```

--------------------------------

### GetSlot - Get specific slot data

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves item data from a specific inventory slot.

```APIDOC
## GetSlot - Get specific slot data

### Description
Returns the item data in a specific inventory slot.

### Method
GET (conceptual)

### Endpoint
exports.ox_inventory:GetSlot(source, slot)

### Parameters
#### Path Parameters
- **source** (string | number) - Required - The identifier for the inventory (e.g., player source, or inventory name like 'police_locker').
- **slot** (number) - Required - The slot number to retrieve data from.

### Request Example
```lua
-- Get item in slot 1
local slot = exports.ox_inventory:GetSlot(source, 1)
if slot then
    print(slot.name, slot.count, slot.metadata.durability)
end
```

### Response
#### Success Response (200)
- **slot** (object) - An object containing item details (name, count, metadata, etc.) or nil if the slot is empty.

#### Response Example
```json
{
  "name": "burger",
  "count": 1,
  "metadata": {
    "durability": 100
  }
}
```
```

--------------------------------

### Get Current Weapon - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves information about the weapon currently equipped by the client. Includes weapon name and metadata such as ammo count.

```lua
local weapon = exports.ox_inventory:getCurrentWeapon()
if weapon then
    print('Holding:', weapon.name)
    print('Ammo:', weapon.metadata.ammo)
end
```

--------------------------------

### Get Inventory Items Only

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns only the items within an inventory, excluding weight and capacity information. Can also retrieve items from specific stashes with an owner identifier.

```lua
local items = exports.ox_inventory:GetInventoryItems(source)
for slot, item in pairs(items) do
    print(slot, item.name, item.count)
end

-- Get stash items with owner
local items = exports.ox_inventory:GetInventoryItems('personal_stash', 'char1:abc123')
```

--------------------------------

### Get Slots With Item - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Finds and returns all slots in the player's inventory that contain the specified item. Returns an empty table if the item is not found.

```lua
local slots = exports.ox_inventory:GetSlotsWithItem('burger')
for _, slot in ipairs(slots) do
    print('Slot', slot.slot, 'has', slot.count, 'burgers')
end
```

--------------------------------

### Get Player Weight - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the current weight of items in the player's inventory. This is useful for tracking carrying capacity.

```lua
local weight = exports.ox_inventory:GetPlayerWeight()
print('Current weight:', weight)
```

--------------------------------

### Get Player Items - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Retrieves all items currently present in the player's inventory. The returned table maps slot numbers to item details, including name and count.

```lua
local items = exports.ox_inventory:GetPlayerItems()
for slot, item in pairs(items) do
    print(slot, item.name, item.count)
end
```

--------------------------------

### Get Slot With Item - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Finds and returns the first slot in the player's inventory that contains the specified item. Returns nil if the item is not found.

```lua
local slot = exports.ox_inventory:GetSlotWithItem('burger')
if slot then
    print('Found burger in slot', slot.slot, 'count:', slot.count)
end
```

--------------------------------

### Get Max Weight - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the maximum weight capacity that the player can carry. This value is typically determined by game mechanics or player stats.

```lua
local maxWeight = exports.ox_inventory:GetPlayerMaxWeight()
print('Max weight:', maxWeight)
```

--------------------------------

### Get Item Count - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns the count of a specific item in the player's inventory. An optional metadata table can be provided for filtering, and a boolean flag can be used to include items in other inventories.

```lua
local count = exports.ox_inventory:GetItemCount('burger')
```

```lua
-- With metadata filter
local count = exports.ox_inventory:GetItemCount('water', { type = 'sparkling' }, true)
```

--------------------------------

### Define Shops in data/shops.lua

Source: https://context7.com/communityox/ox_inventory/llms.txt

Configures shops, including their name, blip information, inventory items with prices, and spawn locations. Supports group-based access and different currency types.

```lua
return {
    General = {
        name = 'Shop',
        blip = { id = 59, colour = 69, scale = 0.8 },
        inventory = {
            { name = 'burger', price = 10 },
            { name = 'water', price = 10 },
            { name = 'phone', price = 500 }
        },
        locations = {
            vec3(25.7, -1347.3, 29.49),
            vec3(-3038.71, 585.9, 7.9)
        },
        targets = {
            { loc = vec3(25.06, -1347.32, 29.5), length = 0.7, width = 0.5, heading = 0.0, minZ = 29.5, maxZ = 29.9, distance = 1.5 }
        }
    },

    PoliceArmoury = {
        name = 'Police Armoury',
        groups = { ['police'] = 0 }, -- Minimum grade 0 required
        inventory = {
            { name = 'WEAPON_PISTOL', price = 500, metadata = { registered = true, serial = 'POL' }, license = 'weapon' },
            { name = 'WEAPON_CARBINERIFLE', price = 1000, metadata = { registered = true }, grade = 3 }, -- Grade 3+ only
            { name = 'ammo-9', price = 5, count = 30 } -- Sells in stacks of 30
        },
        locations = {
            vec3(451.51, -979.44, 30.68)
        }
    },

    BlackMarket = {
        name = 'Black Market',
        inventory = {
            { name = 'WEAPON_CERAMICPISTOL', price = 50000, currency = 'black_money' },
            { name = 'lockpick', price = 100, currency = 'black_money' }
        },
        locations = {
            vec3(309.09, -913.75, 56.46)
        }
    },

    VendingMachine = {
        name = 'Vending Machine',
        inventory = {
            { name = 'water', price = 10 },
            { name = 'cola', price = 10 }
        },
        model = {
            `prop_vend_soda_02`, `prop_vend_water_01`
        }
    }
}
```

--------------------------------

### openInventory

Source: https://context7.com/communityox/ox_inventory/llms.txt

Opens an inventory interface for the local player. Supports various types like stash, shop, player, container, and crafting.

```APIDOC
## openInventory

### Description
Opens an inventory for the local player.

### Method
exports.ox_inventory:openInventory()

### Parameters
- **type** (string) - Optional - The type of inventory (e.g., 'stash', 'shop', 'player', 'container', 'crafting').
- **data** (any) - Optional - The identifier or configuration object for the specific inventory.
```

--------------------------------

### forceOpenInventory - Force open an inventory for a player

Source: https://context7.com/communityox/ox_inventory/llms.txt

Opens an inventory for a player bypassing distance and permission checks.

```APIDOC
## forceOpenInventory - Force open an inventory for a player

### Description
Opens an inventory for a player bypassing distance and permission checks.

### Method
`exports.ox_inventory:forceOpenInventory(source, inventoryType, inventoryName)`

### Parameters
#### Path Parameters
- **source** (number) - Required - The player's source ID.
- **inventoryType** (string) - Required - The type of inventory ('stash', 'container', etc.).
- **inventoryName** (string or number) - Required - The name or ID of the inventory to open.

### Request Example
```lua
-- Force open a stash
exports.ox_inventory:forceOpenInventory(source, 'stash', 'police_locker')

-- Force open a container
exports.ox_inventory:forceOpenInventory(source, 'container', slotId)
```
```

--------------------------------

### forceOpenInventory - Force open an inventory for a player

Source: https://context7.com/communityox/ox_inventory/llms.txt

Opens an inventory for a player bypassing distance and permission checks.

```lua
-- Force open a stash
exports.ox_inventory:forceOpenInventory(source, 'stash', 'police_locker')

-- Force open a container
exports.ox_inventory:forceOpenInventory(source, 'container', slotId)
```

--------------------------------

### Define Crafting Recipes

Source: https://context7.com/communityox/ox_inventory/llms.txt

Configure crafting stations and recipes in data/crafting.lua. Ingredients can include item names and durability percentages for tools.

```lua
return {
    {
        name = 'workbench',
        label = 'Workbench',
        slots = 5,
        items = {
            {
                name = 'lockpick',
                ingredients = {
                    scrapmetal = 5,
                    WEAPON_HAMMER = 0.05 -- Uses 5% durability
                },
                duration = 5000,
                count = 2 -- Creates 2 lockpicks
            },
            {
                name = 'radio',
                ingredients = {
                    scrapmetal = 10,
                    plastic = 5
                },
                duration = 8000,
                count = 1
            }
        },
        points = {
            vec3(-1147.083008, -2002.662109, 13.180260)
        },
        zones = {
            {
                coords = vec3(-1146.2, -2002.05, 13.2),
                size = vec3(3.8, 1.05, 0.15),
                distance = 1.5,
                rotation = 315.0
            }
        },
        blip = { id = 566, colour = 31, scale = 0.8 },
        groups = { ['mechanic'] = 0 } -- Optional group restriction
    }
}
```

--------------------------------

### useItem

Source: https://context7.com/communityox/ox_inventory/llms.txt

Triggers the usage of an item from the inventory.

```APIDOC
## useItem

### Description
Triggers item usage with optional callback.

### Parameters
- **itemData** (table) - Required - Object containing slot and name.
- **callback** (function) - Optional - Callback function executed after usage.
```

--------------------------------

### ReturnInventory - Return confiscated items

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns previously confiscated items to a player.

```lua
-- Return items to player (e.g., when released)
exports.ox_inventory:ReturnInventory(source)
```

--------------------------------

### Open Inventory - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Opens various types of inventories for the local player. Supports player inventory, stashes (with or without owner), shops, other players' inventories, container items, and crafting benches.

```lua
exports.ox_inventory:openInventory()
```

```lua
exports.ox_inventory:openInventory('stash', 'my_stash')
```

```lua
exports.ox_inventory:openInventory('stash', { id = 'personal_locker', owner = GetPlayerServerId(PlayerId()) })
```

```lua
exports.ox_inventory:openInventory('shop', { type = 'General' })
```

```lua
exports.ox_inventory:openInventory('player', targetServerId)
```

```lua
exports.ox_inventory:openInventory('container', slotId)
```

```lua
exports.ox_inventory:openInventory('crafting', { id = 'debug_crafting', index = 1 })
```

--------------------------------

### Server Event: Inventory Opened

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:openedInventory' event on the server, triggered when an inventory is opened.

```lua
-- Inventory opened
AddEventHandler('ox_inventory:openedInventory', function(playerId, inventoryId)
    print(playerId, 'opened inventory', inventoryId)
end)
```

--------------------------------

### CustomDrop - Create a custom item drop

Source: https://context7.com/communityox/ox_inventory/llms.txt

Creates a drop on the ground with specified items.

```lua
-- Create a drop with items
local dropId = exports.ox_inventory:CustomDrop('Loot Bag', {
    { 'burger', 3 },
    { 'water', 5 },
    { 'money', 500 }
}, vec3(200.0, 300.0, 30.0))

-- Create instanced drop (only visible in specific routing bucket)
local dropId = exports.ox_inventory:CustomDrop('Heist Bag', {
    { 'black_money', 50000 }
}, vec3(100.0, 200.0, 25.0), 30, 100000, instanceId, `prop_paper_bag_01`)
-- slots: 30, maxWeight: 100000, instance: instanceId, model: prop_paper_bag_01
```

--------------------------------

### ReturnInventory - Return confiscated items

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns previously confiscated items to a player.

```APIDOC
## ReturnInventory - Return confiscated items

### Description
Returns previously confiscated items to a player.

### Method
`exports.ox_inventory:ReturnInventory(source)`

### Parameters
#### Path Parameters
- **source** (number) - Required - The player's source ID.

### Request Example
```lua
-- Return items to player (e.g., when released)
exports.ox_inventory:ReturnInventory(source)
```
```

--------------------------------

### giveItemToTarget

Source: https://context7.com/communityox/ox_inventory/llms.txt

Gives an item from the local player's inventory to a target player.

```APIDOC
## giveItemToTarget

### Description
Gives an item from your inventory to a target player.

### Parameters
- **targetServerId** (number) - Required - The server ID of the target player.
- **slotId** (number) - Required - The slot ID of the item.
- **count** (number) - Required - The amount to give.
```

--------------------------------

### Client Event: Item Used

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:usedItem' event on the client, triggered when an item is used.

```lua
-- Item used
AddEventHandler('ox_inventory:usedItem', function(name, slot, metadata)
    print('Used item:', name, 'from slot', slot)
end)
```

--------------------------------

### GetPlayerItems

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns all items currently in the player's inventory.

```APIDOC
## GetPlayerItems

### Description
Returns all items in the player's inventory.
```

--------------------------------

### Server Event: Custom Drop

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles a custom drop event on the server, allowing custom logic for dropped items.

```lua
-- Custom drop event
AddEventHandler('ox_inventory:customDrop', function(prefix, items, coords, slots, maxWeight, instance, model)
    -- Handle custom drops
end)
```

--------------------------------

### Define Container Items in modules/items/containers.lua

Source: https://context7.com/communityox/ox_inventory/llms.txt

Configures container items, specifying their storage capacity in slots and maximum weight. Supports whitelisting or blacklisting specific items.

```lua
return {
    ['paperbag'] = {
        size = { 5, 1000 }, -- 5 slots, 1000g max weight
    },
    ['backpack'] = {
        size = { 15, 15000 },
        whitelist = { 'burger', 'water' }, -- Only these items allowed
    },
    ['briefcase'] = {
        size = { 10, 10000 },
        blacklist = { 'WEAPON_PISTOL' } -- These items not allowed
    }
}
```

--------------------------------

### ConfiscateInventory - Confiscate player items

Source: https://context7.com/communityox/ox_inventory/llms.txt

Moves all items to a confiscated storage for later retrieval.

```lua
-- Confiscate player's inventory (e.g., when arrested)
exports.ox_inventory:ConfiscateInventory(source)
```

--------------------------------

### Search

Source: https://context7.com/communityox/ox_inventory/llms.txt

Searches the local player's inventory for items based on count or slot location.

```APIDOC
## Search

### Description
Searches the local player's inventory for items.

### Parameters
- **type** (string) - Required - The search type ('count' or 'slots').
- **item** (string/table) - Required - The item name or list of item names.
- **metadata** (table) - Optional - Metadata filter for the search.
```

--------------------------------

### Define Items in data/items.lua

Source: https://context7.com/communityox/ox_inventory/llms.txt

Defines various items with properties like label, weight, stackability, and client-side effects. Some items have specific consumption or degradation values.

```lua
return {
    ['burger'] = {
        label = 'Burger',
        weight = 220,
        stack = true,
        close = true,
        description = 'A delicious burger',
        degrade = 60, -- Degrades after 60 minutes
        consume = 1, -- Consumes 1 on use
        client = {
            status = { hunger = 200000 },
            anim = 'eating',
            prop = 'burger',
            usetime = 2500,
            notification = 'You ate a delicious burger',
            cancel = true -- Can cancel the progress bar
        }
    },

    ['bandage'] = {
        label = 'Bandage',
        weight = 115,
        consume = 0.2, -- Uses 20% durability per use
        client = {
            anim = { dict = 'missheistdockssetup1clipboard@idle_a', clip = 'idle_a', flag = 49 },
            prop = { model = `prop_rolled_sock_02`, pos = vec3(-0.14, -0.14, -0.08), rot = vec3(-50.0, -50.0, 0.0) },
            disable = { move = true, car = true, combat = true },
            usetime = 2500
        }
    },

    ['phone'] = {
        label = 'Phone',
        weight = 190,
        stack = false,
        consume = 0, -- Not consumed on use
        client = {
            add = function(total)
                if total > 0 then
                    exports.npwd:setPhoneDisabled(false)
                end
            end,
            remove = function(total)
                if total < 1 then
                    exports.npwd:setPhoneDisabled(true)
                end
            end
        }
    },

    ['backpack'] = {
        label = 'Backpack',
        weight = 500,
        stack = false,
        close = false,
        consume = 0
        -- Container items get metadata.container and metadata.size automatically
    },

    ['testburger'] = {
        label = 'Test Burger',
        weight = 220,
        degrade = 60,
        client = {
            image = 'burger_chicken.png',
            status = { hunger = 200000 },
            export = 'ox_inventory_examples.testburger'
        },
        server = {
            export = 'ox_inventory_examples.testburger'
        },
        buttons = {
            {
                label = 'Inspect',
                action = function(slot)
                    print('Inspecting burger in slot', slot)
                end
            }
        },
        consume = 0.3 -- Uses 30% durability
    }
}
```

--------------------------------

### CreateTemporaryStash - Create a temporary stash

Source: https://context7.com/communityox/ox_inventory/llms.txt

Creates a temporary stash that isn't saved to the database.

```lua
-- Create loot drop
local stashId = exports.ox_inventory:CreateTemporaryStash({
    label = 'Crashed Truck',
    slots = 20,
    maxWeight = 50000,
    coords = vec3(100.0, 200.0, 30.0),
    items = {
        { 'burger', 5 },
        { 'water', 10 },
        { 'WEAPON_PISTOL', 1, { durability = 50, ammo = 15 } }
    }
})

-- Group-restricted temp stash
local stashId = exports.ox_inventory:CreateTemporaryStash({
    label = 'Evidence Box',
    slots = 50,
    maxWeight = 100000,
    owner = 'case_12345',
    groups = { police = 0 }
})

-- Open the temporary stash
exports.ox_inventory:forceOpenInventory(source, 'stash', stashId)
```

--------------------------------

### AddItem - Add items to an inventory

Source: https://context7.com/communityox/ox_inventory/llms.txt

Adds one or more items to the specified inventory with optional metadata and slot targeting.

```lua
-- Add 5 burgers to player with source id 1
local success, response = exports.ox_inventory:AddItem(1, 'burger', 5)

-- Add item with custom metadata
local success, response = exports.ox_inventory:AddItem(source, 'water', 1, { label = 'Sparkling Water' })

-- Add item to specific slot
local success, response = exports.ox_inventory:AddItem(source, 'phone', 1, { number = '555-1234' }, 5)

-- Add weapon with metadata
local success, response = exports.ox_inventory:AddItem(source, 'WEAPON_PISTOL', 1, {
    durability = 100,
    ammo = 30,
    registered = 'John Doe',
    serial = 'ABC123456DEF'
})

if success then
    print('Item added to slot:', response.slot)
else
    print('Failed:', response) -- 'invalid_item', 'invalid_count', 'inventory_full'
end
```

--------------------------------

### ConfiscateInventory - Confiscate player items

Source: https://context7.com/communityox/ox_inventory/llms.txt

Moves all items to a confiscated storage for later retrieval.

```APIDOC
## ConfiscateInventory - Confiscate player items

### Description
Moves all items to a confiscated storage for later retrieval.

### Method
`exports.ox_inventory:ConfiscateInventory(source)`

### Parameters
#### Path Parameters
- **source** (number) - Required - The player's source ID.

### Request Example
```lua
-- Confiscate player's inventory (e.g., when arrested)
exports.ox_inventory:ConfiscateInventory(source)
```
```

--------------------------------

### Server Event: Player Used Item

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:usedItem' event on the server, triggered when a player uses an item.

```lua
-- Player used an item
AddEventHandler('ox_inventory:usedItem', function(playerId, itemName, slotId, metadata)
    print(playerId, 'used', itemName, 'from slot', slotId)
end)
```

--------------------------------

### Check if Inventory Can Hold Item

Source: https://context7.com/communityox/ox_inventory/llms.txt

Verifies if the inventory has sufficient weight and slot capacity for a given item and quantity, optionally considering item metadata for custom weight. Use before adding items to prevent overflow.

```lua
-- Check if player can carry 5 burgers
if exports.ox_inventory:CanCarryItem(source, 'burger', 5) then
    exports.ox_inventory:AddItem(source, 'burger', 5)
else
    TriggerClientEvent('ox_lib:notify', source, { type = 'error', description = 'Inventory full!' })
end

-- Check with metadata (for custom weight)
local canCarry = exports.ox_inventory:CanCarryItem(source, 'backpack', 1, { weight = 5000 })
```

--------------------------------

### Search - Search inventory for items

Source: https://context7.com/communityox/ox_inventory/llms.txt

Searches an inventory for items, returning either slot data or counts.

```lua
-- Get count of single item
local count = exports.ox_inventory:Search(source, 'count', 'burger')
print('Burgers:', count) -- 5

-- Get count of multiple items
local counts = exports.ox_inventory:Search(source, 'count', { 'burger', 'water' })
print('Burgers:', counts.burger, 'Water:', counts.water)

-- Get slots containing item
local slots = exports.ox_inventory:Search(source, 'slots', 'burger')
for _, slot in pairs(slots) do
    print('Slot:', slot.slot, 'Count:', slot.count, 'Metadata:', json.encode(slot.metadata))
end

-- Search with metadata filter
local slots = exports.ox_inventory:Search(source, 'slots', 'water', { type = 'sparkling' })
```

--------------------------------

### Client Event: Inventory Updated

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:updateInventory' event on the client, triggered when the inventory contents change. It iterates through changes and prints slot information.

```lua
-- Inventory updated
AddEventHandler('ox_inventory:updateInventory', function(changes)
    for slot, item in pairs(changes) do
        if item then
            print('Slot', slot, ':', item.name, 'x', item.count)
        else
            print('Slot', slot, 'cleared')
        end
    end
end)
```

--------------------------------

### ClearInventory - Remove all items from inventory

Source: https://context7.com/communityox/ox_inventory/llms.txt

Wipes all items from the specified inventory.

```lua
-- Clear player inventory
exports.ox_inventory:ClearInventory(source)

-- Clear with exception (keep certain items)
exports.ox_inventory:ClearInventory(source, 'phone')

-- Keep multiple items
exports.ox_inventory:ClearInventory(source, { 'phone', 'money', 'identification' })

-- Clear a stash
exports.ox_inventory:ClearInventory('evidence_locker')
```

--------------------------------

### GetItem

Source: https://context7.com/communityox/ox_inventory/llms.txt

Returns item data including current count from a player's inventory.

```APIDOC
## GetItem

### Description
Returns item data including current count from a player's inventory.

### Parameters
- **inventory** (string/number) - Required - The inventory identifier or source ID.
- **item** (string) - Required - The item name.
- **metadata** (table) - Optional - Metadata filter.
- **onlyCount** (boolean) - Optional - If true, returns only the count.
```

--------------------------------

### Define Stashes

Source: https://context7.com/communityox/ox_inventory/llms.txt

Configure personal or shared storage locations in data/stashes.lua. Use the owner flag to create unique inventories per player.

```lua
return {
    {
        coords = vec3(452.3, -991.4, 30.7),
        target = {
            loc = vec3(451.25, -994.28, 30.69),
            length = 1.2,
            width = 5.6,
            heading = 0,
            minZ = 29.49,
            maxZ = 32.09,
            label = 'Open personal locker'
        },
        name = 'policelocker',
        label = 'Personal locker',
        owner = true, -- Each player gets their own
        slots = 70,
        weight = 70000,
        groups = { ['police'] = 0 }
    },

    {
        coords = vec3(301.3, -600.23, 43.28),
        name = 'emslocker',
        label = 'EMS Locker',
        owner = true,
        slots = 70,
        weight = 70000,
        groups = { ['ambulance'] = 0 }
    }
}
```

--------------------------------

### CustomDrop - Create a custom item drop

Source: https://context7.com/communityox/ox_inventory/llms.txt

Creates a drop on the ground with specified items.

```APIDOC
## CustomDrop - Create a custom item drop

### Description
Creates a drop on the ground with specified items.

### Method
`exports.ox_inventory:CustomDrop(label, items, coords, [slots], [maxWeight], [instance], [model])`

### Parameters
#### Path Parameters
- **label** (string) - Required - Display name for the drop.
- **items** (table) - Required - Items to place in the drop. Each item is a table like `{ name, count, metadata }`.
- **coords** (vector3) - Required - Coordinates for the drop location.
- **slots** (number) - Optional - The number of slots available in the drop.
- **maxWeight** (number) - Optional - The maximum weight capacity of the drop.
- **instance** (number) - Optional - The routing bucket instance ID.
- **model** (string) - Optional - The model name for the prop representing the drop.

### Request Example
```lua
-- Create a drop with items
local dropId = exports.ox_inventory:CustomDrop('Loot Bag', {
    { 'burger', 3 },
    { 'water', 5 },
    { 'money', 500 }
}, vec3(200.0, 300.0, 30.0))

-- Create instanced drop (only visible in specific routing bucket)
local dropId = exports.ox_inventory:CustomDrop('Heist Bag', {
    { 'black_money', 50000 }
}, vec3(100.0, 200.0, 25.0), 30, 100000, instanceId, `prop_paper_bag_01`)
-- slots: 30, maxWeight: 100000, instance: instanceId, model: prop_paper_bag_01
```
```

--------------------------------

### Search

Source: https://context7.com/communityox/ox_inventory/llms.txt

Searches an inventory for items, returning either slot data or counts.

```APIDOC
## Search

### Description
Searches an inventory for items, returning either slot data or counts.

### Parameters
- **inventory** (string/number) - Required - The inventory identifier or source ID.
- **type** (string) - Required - Search type ('count' or 'slots').
- **item** (string/table) - Required - Item name or list of names.
- **metadata** (table) - Optional - Metadata filter.
```

--------------------------------

### AddItem

Source: https://context7.com/communityox/ox_inventory/llms.txt

Adds one or more items to the specified inventory with optional metadata and slot targeting.

```APIDOC
## AddItem

### Description
Adds one or more items to the specified inventory with optional metadata and slot targeting.

### Parameters
- **inventory** (string/number) - Required - The inventory identifier or source ID.
- **item** (string) - Required - The item name.
- **count** (number) - Required - The quantity to add.
- **metadata** (table) - Optional - Custom item metadata.
- **slot** (number) - Optional - Specific slot to add the item to.

### Response
- **success** (boolean) - Whether the operation succeeded.
- **response** (table/string) - Contains slot information on success or error code on failure.
```

--------------------------------

### Server Event: Inventory Closed

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:closedInventory' event on the server, triggered when an inventory is closed.

```lua
-- Inventory closed
AddEventHandler('ox_inventory:closedInventory', function(playerId, inventoryId)
    print(playerId, 'closed inventory', inventoryId)
end)
```

--------------------------------

### Check Available Weight Capacity

Source: https://context7.com/communityox/ox_inventory/llms.txt

Determines if the inventory can accommodate additional weight and reports the remaining available weight. Useful for managing weight limits.

```lua
-- Check if player can carry 5000 grams
local canCarry, availableWeight = exports.ox_inventory:CanCarryWeight(source, 5000)
if canCarry then
    print('Can carry! Available weight:', availableWeight)
end
```

--------------------------------

### GetSlotWithItem - Find first slot containing item

Source: https://context7.com/communityox/ox_inventory/llms.txt

Finds the first slot that contains a specific item, with optional metadata matching.

```APIDOC
## GetSlotWithItem - Find first slot containing item

### Description
Returns the first slot containing the specified item with optional metadata matching.

### Method
GET (conceptual)

### Endpoint
exports.ox_inventory:GetSlotWithItem(source, item_name, metadata, strict_metadata_match)

### Parameters
#### Path Parameters
- **source** (string | number) - Required - The identifier for the inventory.
- **item_name** (string) - Required - The name of the item to search for.
- **metadata** (object) - Optional - An object containing metadata to filter by.
- **strict_metadata_match** (boolean) - Optional - If true, all provided metadata fields must match exactly. Defaults to false.

### Request Example
```lua
-- Find first slot with burger
local slot = exports.ox_inventory:GetSlotWithItem(source, 'burger')
print('Found burger in slot:', slot.slot)

-- Find with metadata filter (strict matching)
local slot = exports.ox_inventory:GetSlotWithItem(source, 'water', { type = 'sparkling' }, true)
```

### Response
#### Success Response (200)
- **slot** (object) - An object containing slot details (including slot number) or nil if the item is not found.

#### Response Example
```json
{
  "slot": 5,
  "name": "burger",
  "count": 1,
  "metadata": {}
}
```
```

--------------------------------

### CanCarryWeight - Check available weight capacity

Source: https://context7.com/communityox/ox_inventory/llms.txt

Checks if an inventory has enough available weight capacity to carry additional items.

```APIDOC
## CanCarryWeight - Check available weight capacity

### Description
Checks if inventory can hold additional weight.

### Method
GET (conceptual)

### Endpoint
exports.ox_inventory:CanCarryWeight(source, weight_to_add)

### Parameters
#### Path Parameters
- **source** (string | number) - Required - The identifier for the inventory.
- **weight_to_add** (number) - Required - The amount of weight to check capacity for.

### Request Example
```lua
-- Check if player can carry 5000 grams
local canCarry, availableWeight = exports.ox_inventory:CanCarryWeight(source, 5000)
if canCarry then
    print('Can carry! Available weight:', availableWeight)
end
```

### Response
#### Success Response (200)
- **canCarry** (boolean) - True if the weight can be carried, false otherwise.
- **availableWeight** (number) - The remaining weight capacity in the inventory.

#### Response Example
```json
{
  "canCarry": true,
  "availableWeight": 15000
}
```
```

--------------------------------

### Find First Slot Containing Item

Source: https://context7.com/communityox/ox_inventory/llms.txt

Locates the first slot that contains a specified item, with optional strict metadata matching. Useful for quick checks or when only one instance is needed.

```lua
-- Find first slot with burger
local slot = exports.ox_inventory:GetSlotWithItem(source, 'burger')
print('Found burger in slot:', slot.slot)

-- Find with metadata filter (strict matching)
local slot = exports.ox_inventory:GetSlotWithItem(source, 'water', { type = 'sparkling' }, true)
```

--------------------------------

### Give Item to Target - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Transfers an item from the player's inventory to a nearby target player. Requires the target player's server ID, the slot ID of the item, and the count of the item to transfer.

```lua
exports.ox_inventory:giveItemToTarget(targetServerId, slotId, count)
```

--------------------------------

### Client Event: Current Weapon Changed

Source: https://context7.com/communityox/ox_inventory/llms.txt

Handles the 'ox_inventory:currentWeapon' event on the client, triggered when the player's equipped weapon changes.

```lua
-- Current weapon changed
AddEventHandler('ox_inventory:currentWeapon', function(weapon)
    if weapon then
        print('Equipped:', weapon.name)
    else
        print('Weapon holstered')
    end
end)
```

--------------------------------

### Use Item - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Triggers the usage of an item from a specific inventory slot. An optional callback function can be provided to handle the result of the item usage.

```lua
-- Use item in specific slot
exports.ox_inventory:useItem({ slot = 1, name = 'burger' }, function(data)
    if data then
        print('Used item:', data.name)
    end
end)
```

--------------------------------

### Use Slot - ox_inventory API

Source: https://context7.com/communityox/ox_inventory/llms.txt

Uses the item located in the specified inventory slot. This is a direct way to trigger an item's primary action.

```lua
exports.ox_inventory:useSlot(1) -- Use item in slot 1
```

--------------------------------

### SetItem - Set item count in inventory

Source: https://context7.com/communityox/ox_inventory/llms.txt

Sets the count of an item to a specific value, adding or removing as needed.

```lua
-- Set player to have exactly 10 burgers
local success, response = exports.ox_inventory:SetItem(source, 'burger', 10)

-- Set item with metadata
local success = exports.ox_inventory:SetItem(source, 'water', 5, { type = 'sparkling' })

-- Remove all of an item (set to 0)
local success = exports.ox_inventory:SetItem(source, 'garbage', 0)
```