Arrays

Arrays are a series of values of the same type. They are referenced by their index, which is an integer value starting at 0. This means the index of the first element in the array is 0.

The Plex API uses arrays to add values to a field that can contain multiple values. An example of this is the Genre field of a movie, which can have multiple values such as "Drama" and "Adventure".

Updating field values

When updating or adding values for fields that use an array, you would specify the field name, the index, and the value. For example, the following will add "Action" to the genre field for a movie:

genre[0].tag.tag=Action

The double ".tag" values are necessary. The genre[0].tag indicates that the field is the genre tag. The second ".tag" indicates to "tag" the "Action" value to the genre. Any fields that accept an array of values are updated in this manner.

When using the Plex API, you would be sending the field names and values as parameters in a request. To specify the index of the array, you would need to encode the square brackets before sending them as parameters in the request as such:

genre%5B0%5D.tag.tag=Action

In the above example, "[" was encoded to %5B, and "]" was encoded to %5D.

By default, HTML5 uses the UTF-8 character set. Here is a list of UTF-8 encoded characters for reference.

When specifying values in an array, the specified values do not overwrite existing values in the field; the new values are appended to the existing values.

For example, if a media item has "Action" as the value in index 0 of the genre, adding "Adventure" as index 0 will make both "Action" and "Adventure" genres for the media item.

While the index numbers do not need to start at 0, it is recommended.

Updating multiple values

To add multiple values to a field, you would include each value as a separate parameter, each with a different index:

genre%5B0%5D.tag.tag=Action&genre%5B1%5D.tag.tag=Adventure

The above will add both "Action" and "Adventure" to the genre field for a media item. If another value exists at either index 0 or index 1, then "Action" and "Adventure" would be added to the existing list of items.

Removing values from a field

To remove an item from an array of values in a field, you would use '-=' without specifying an index value.

For example, to remove the "Action" genre for the media item you would use

genre%5B%5D.tag.tag-=Action

Note that the encoded square brackets are still included in the parameter name.

If you would like to remove multiple values from the field, you can specify all the values, separated by an encoded "," (comma):

genre%5B%5D.tag.tag-=Action%2CAdventure

The above will remove the values "Action" and "Adventure" from the genre field for the media item.