Linden Lab Official:Inventory API
This document uses LLIDL for terse description of the HTTP POST and response bodies.
Viewer Capabilities
The Viewer receives four Inventory API capabilities. As of January, 2011, we have deployed version-2 identified capabilities and removed all others. These capabilities will be used by default on Viewer 2.6 and above. Third Party Viewers are welcomed to update their code, but to be aware the pre-Viewer-2.6 code has numerous bugs associated with this method of accessing inventory.
Note: descendants is frequently but haphazardly misspelled as descendents in the code. These misspellings are fixed in place due to existing widespread deployment. Fortunately, Merriam-Webster says that this is an acceptable alternate spelling :).
FetchInventoryDescendents2
Follows the Fetch Inventory Descendents API, fetches the agent's inventory structure.
FetchInventory2
Follows the Fetch Inventory Items API, fetches the agent's items.
FetchLibDescendents2
Follows the Fetch Inventory Descendents API, fetches library inventory structure.
FetchLib2
Follows the Fetch Inventory Items API, fetches library inventory items.
Structures
The Inventory API returns values that use the following standardized LLSD data structures:
- Category - can contain items and other categories.
- Item - A handle that can point to a valid asset in the system.
- Permission - permissions information for an item.
- Sale info - information on sale of an item
Categories and items are not required to have unique names. The system generates all categories with a non-null asset_type and you cannot delete them. All user-generated categories have type_default null.
Category
The category data structure can contain items and other categories. The combination of agent_id and category_id uniquely identify a category. A special root category has type_default = folder (a category for folders) and a parent_id of null UUID (00000000-0000-0000-0000-000000000000).
The category data structure consists of a single LLSD map with the values described in the following table.
| Key | Datatype | Description |
|---|---|---|
| agent_id | UUID | Agent's UUID |
| category_id | UUID | Category's UUID |
| name | string | Text name of the category |
| parent_id | UUID | Parent category's UUID |
| type_default | integer | Asset type value. |
| version | integer | Version number |
LLIDL
<python>&category = {
agent_id : uuid, category_id : uuid, parent_id : uuid, name : string, type_default : int, version : int, }</python>
Item
The item data structure refers to a valid asset in the system and contains enough information to find the asset in our domain, as well as permissions information. An item is uniquely identified by the combination of agent_id and item_id.
The item data structure consists of a map containing the following elements:
| Return value | Datatype | Description |
|---|---|---|
| agent_id | UUID | |
| asset_id | UUID | |
| created_at | int | timestamp? |
| desc | string | |
| flags | integer | |
| inv_type | integer | inventory type |
| item_id | UUID | |
| name | string | |
| parent_id | UUID | |
| permissions | Map containing Permissions | |
| sale_info | Map containing Sale info | |
| type | integer | asset type |
LLIDL
<python>&item = {
agent_id : uuid, item_id : uuid, parent_id : uuid, (category_id of the containing folder) asset_id : uuid, (available only for downloadable assets) name : string, desc : string, created_at : int, (timestamp) type : int, (asset type) inv_type : int, (inventory type) flags : int, (type-specific flags) permissions : &permissions, sale_info : &sale_info, }</python>
Permissions
The permissions structure is a map containing the following elements:
| Return value | Datatype | Description |
|---|---|---|
| base_mask | integer | |
| creator_id | UUID | |
| everyone_mask | integer | |
| group_id | UUID | if the object is group-owned, this will have a value. |
| group_mask | integer | |
| is_owner_group | bool | |
| last_owner_id | UUID | |
| next_owner_mask | integer | |
| owner_id | UUID | always same as agent_id |
| owner_mask | integer |
LLIDL
<python>&permissions = {
creator_id : uuid, owner_id : uuid, (always same as agent_id) group_id : uuid, last_owner_id : uuid, is_owner_group : bool, base_mask : int, group_mask : int, owner_mask : int, next_owner_mask : int, everyone_mask : int, }</python>
Sale info
The sale info structure is a map containing the following elements:
| Return value | Datatype | Description |
|---|---|---|
| sale_price | integer | |
| sale_type | integer |
LLIDL
<python>&sale_info = {
sale_price : int, sale_type : int, }</python>
Links
Item Links
Item links have inventory_type 24. The asset_id field of the item points to an item_id. When the parent category contents are retrieved, both the link item and the link target appear in the listing. Viewer must resolve the links by using the target item's information and removing the target item from the listing. Broken links, that is, a link item for which there is no corresponding target item, must be shown as broken links, allowing the user to take corrective action.
Folder Links
Folder links are represented by items with inventory_type 25. The asset_id field of the item points to a category_id. Viewers should enable viewing of the contents of the target category, while indicating that the category is a link.
API
Fetch Inventory Items
Returns information on the specified inventory items.
HTTP method: POST
Path:
FetchInventoryCapURL
Parameters
Query (POST) parameters:
- items - a map with one key, 'items', whose value is an array of maps, each with one key, 'item_id', whose value is the item you want information about.
Return value
The response is a map containing two keys, as shown in the following table.
| Key | Datatype | Description |
|---|---|---|
| agent_id | UUID | UUID of the agent in question |
| items | array | Array of item data structures. |
Each item data structure is a map with the following elements:
| Return value | Datatype | Description |
|---|---|---|
| agent_id | UUID | |
| asset_id | UUID | |
| created_at | int | timestamp |
| desc | string | |
| flags | integer | |
| inv_type | integer | inventory type |
| item_id | UUID | |
| name | string | |
| parent_id | UUID | |
| permissions | Map containing Permissions | |
| sale_info | Map containing Sale info | |
| type | integer | asset type |
Example
TBD
LLIDL
<python>
%% FetchInventoryCapURL
-> { items: [{ item_id: uuid }, ... ] }
<- { agent_id: uuid, items: [ &item, ... ] }
</python>
Fetch Inventory Descendents
HTTP method: POST
Path:
FetchInventoryDescendentsCapURL
Using HTTP POST, send a body containing a map with one key, 'folders', whose value is an array of maps, each with one key, 'folder_id', each of whose value is the category you want information about.
The response is a map containing one key, 'folders', whose value is an array of folder structures with bonus descendents information.
Parameters
Query parameters:
- folder_ids - map with one key, 'folders', whose value is an array of maps, each with one key, 'folder_id', each of whose value is the UUID of the category on which you want information.
Return value
Returns a map with a single element, folders, that is an array with a single element that is a map with the following elements:
| Key | Datatype | Description |
|---|---|---|
| agentid | UUID | UUID of the agent in question |
| owner_id | undef | |
| folder_id | UUID | |
| version | int | |
| descendents | int | Note typo! |
| categories | Array of category data structure | See below for elements. |
| items | Array of item data structures. | See below for elements. |
Each category data structure is a map with the following elements: {{#lst:Inventory API|category }}
Each item data structure is a map with the following elements: {{#lst:Inventory API|item}}
Example
TBD
LLIDL
<python>
%% FetchInventoryDescendentsCapURL
-> { folders: [{ folder_id: uuid }, ... ] }
<- { folders: [{ agent_id: uuid,
owner_id: uuid,
folder_id: uuid,
version: int,
descendents: int, (len(items) + len(categories))
categories: [ &category, ... ],
items: [ &item, ... ]
}] }
</python>