> ## Documentation Index
> Fetch the complete documentation index at: https://docs.forgegames.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Item Instances

> Create and manage individual occurrences of items with unique properties

## What are Item Instances?

Item Instances are unique occurrences of items that inherit their properties from item templates. They allow you to give each item specific attributes, modifiers, or states that distinguish it from others.

For example:

* A "Sword" template might define base damage and durability.
* An instance of that sword can have rolled attributes, such as **damage: 45** and **durability: 90**, making it unique.

### Item Instance Properties

| Property     | Type   | Description                                       |
| ------------ | ------ | ------------------------------------------------- |
| `id`         | String | The unique identifier for the item instance.      |
| `itemId`     | String | The ID of the template the instance is based on.  |
| `attributes` | Object | Key-value pairs of attribute names and values.    |
| `createdAt`  | String | The timestamp when the instance was created.      |
| `updatedAt`  | String | The timestamp of the last update (if applicable). |

<Tip>
  Use item instances to track the unique properties and states of items owned by
  players.
</Tip>

## Example Configuration

### Template

| Property     | Value                           |
| ------------ | ------------------------------- |
| `itemId`     | swordTemplate                   |
| `attributes` | `{damage: 20, durability: 100}` |

### Instance

| Property     | Value                          |
| ------------ | ------------------------------ |
| `id`         | swordInstance123               |
| `attributes` | `{damage: 45, durability: 90}` |

In this example, the instance has rolled higher damage and durability values than the template, creating a unique and powerful weapon.

***

## API Reference

### Create an Item Instance

**Endpoint**:\
`POST /teams/{teamId}/item-instances`

**Description**:\
Creates a new item instance based on a template and applies custom attributes or modifiers.

**Request Body**:

```json theme={null}
{
  "itemId": "swordTemplate",
  "attributes": {
    "damage": 45,
    "durability": 90
  },
  "userId": "player123"
}
```

**Response**:

```json theme={null}
{
  "id": "swordInstance123",
  "itemId": "swordTemplate",
  "attributes": {
    "damage": 45,
    "durability": 90
  },
  "createdAt": "2024-01-01T12:00:00Z"
}
```

### List Item Instances

**Endpoint**:\
`GET /teams/{teamId}/item-instances`

**Description**:\
Lists all item instances within a team, with optional filters for users, items, or attributes.

**Response**:

```json theme={null}
[
  {
    "id": "swordInstance123",
    "itemId": "swordTemplate",
    "attributes": {
      "damage": 45,
      "durability": 90
    },
    "createdAt": "2024-01-01T12:00:00Z"
  }
]
```

By leveraging item instances, you can create unique, dynamic items that enhance gameplay and player engagement.

***

### Key Elements:

1. **Rolling**:
   * Explains probabilities and mechanics.
   * Ties classifiers and attributes together to show how they work in practice.
   * Includes an API reference for performing rolls.
2. **Item Instances**:
   * Focuses on creating and managing unique items.
   * Highlights the relationship between templates and instances.
   * Includes API references for creation and listing.

Let me know if you'd like further refinements!

```
```