Array API
When to use the Array API
Use the Array API for collections such as favorites, watch history, and recently viewed content. New integrations should use customer-owned itemId values to address items without a preliminary read.
All examples use the USER scope and content:favorites key. See the Personalization overview for authentication, scopes, key syntax, and shared limits.
Array data model
Array key
An array is identified by its authenticated scope and key, for example content:favorites.
Item value
An item value is valid JSON. It may be a scalar, object, or array. It does not need to contain an id field and does not need to repeat itemId.
Customer-owned itemId
itemId is the stable domain identifier supplied by the customer. It must match ^[\\w-]+(:[\\w-]+)*$ and may be at most 256 characters. For example, movie:100 can identify a favorite movie.
itemId is authoritative for items written by the new API. It does not need to equal value.id.
Service-generated id
id is generated by the service and is returned with each array item. It is useful for the supported single-item operations getArrayItem and deleteArrayItem. New integrations should normally retain and use itemId as domain identity.
Sort fields
| Field | Type | Owner |
|---|---|---|
sortString | String | Customer |
sortNumber | Int | Customer |
sortDate | Datetime | Customer |
dateModified | Datetime | Service |
id | Service-generated ID | Service |
Choose an operation
| Goal | Operation | Status |
|---|---|---|
| Traverse all items | listArrayItems | Recommended |
| Find selected items | lookupArrayItems | Recommended |
Insert or update by itemId | upsertArrayItem | Recommended |
| Replace the complete array | replaceArrayItems | Recommended |
| Delete selected items | deleteArrayItems | Recommended |
| Read one item by service-generated ID | getArrayItem | Supported |
| Delete one item by service-generated ID | deleteArrayItem | Supported |
| Delete the complete array | deleteArray | Supported |
| Offset-paginate an array | getArray | Deprecated |
| Insert/update using an optional service-generated ID | setArrayItem | Deprecated |
| Replace an array without explicit item IDs | setArray | Deprecated |
Deprecated operations. getArray, setArrayItem, and setArray remain available for compatibility, but they are deprecated. No removal date is currently scheduled. Use the replacement operations in the table above for new integrations.
Recommended item lifecycle
- Choose a stable domain identifier such as
movie:100. - Write with
upsertArrayItem. - Read with
listArrayItemsorlookupArrayItems. - Delete selected items with
deleteArrayItems, or clear the array withdeleteArray. - Use cursor pagination and sorting for repeatable traversal.
Existing-data compatibility
A stored string itemId is authoritative. Older items without stored itemId can be addressable when their own value.id is a qualifying legacy identity. Reads do not backfill or modify those items. Upsert can migrate a matching legacy item and remove matching duplicates.
See Migrate from deprecated Array APIs for compatibility details.