Individual items can be added and removed from a sequence using the Sequence Manipulation API.

This API is useful for single item operations within a sequence and avoids client-side manipulation of the entire sequence.

The API expects an item in the request body. Alternatively, an existing library item can be referenced by ID. When an ID is specified additional data can be provided to customise the item.

Path syntax

[METHOD] /rest-api/v1/op/sequence/[SEQUENCE-ID]/[SLOT-NUMBER]/[ITEM-NUMBER]

The type property must be set to libraryitem. Arrays of items are supported. See examples below.

Single item operations

Add a new item

Create a new item and add it to a new stack at the end of a sequence.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]
{
  "type" : "libraryitem",
  "data" : {
    "label" : "TargetR Logo",
  },
  "resources" : [ {
    "type" : "static",
    "data" : {
      "blobId" : "ECF7E77D8CE1E5387045BB0F1F8E5BE8-3937",
      "width" : "100",
      "contentLength" : "3937",
      "contentType" : "image/png",
      "height" : "100"
    }
  } ]
}

Create a new item based on a library item and add it to a new stack at the end of a sequence.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]"
}

Create a new item based on a library item, apply a new label, and add it to a new stack at the end of a sequence.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]",
  "data" : { "label" : "My new item label", }
}

Create a new item based on a library item and add it to a new stack in the 2nd slot of a sequence. Subsequent stacks shift right.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]/2
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]"
}

Create a new item based on a library item and add it to the 3rd position of the 2nd stack in a sequence. Subsequent items in the 2nd stack shift down.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]/2/3
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]"
}

Replace an existing item with a new item

Create a new item based on a library item and replace the item in the 3rd position of the 2nd stack in a sequence with the new item.

PUT /rest-api/v1/op/sequence/[SEQUENCE-ID]/2/3
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]"
}

Replace an existing stack with a new stack containing a new item

Create a new item based on a library item inside a new stack and replace the 2nd stack in a sequence with the new stack.

PUT /rest-api/v1/op/sequence/[SEQUENCE-ID]/2
{
  "type" : "libraryitem",
  "id" : "[LIBRARYITEM-ID]"
}

Remove an item

Remove the item in the 3rd position of the 2nd stack. Subsequent items in the 2nd stack shift up.

DELETE /rest-api/v1/op/sequence/[SEQUENCE-ID]/2/3

Remove a stack

Remove the stack in the 2nd slot. Subsequent stacks shift left.

DELETE /rest-api/v1/op/sequence/[SEQUENCE-ID]/2

Fetch an item

Fetch the item in the 3rd position of the 2nd stack.

GET /rest-api/v1/op/sequence/[SEQUENCE-ID]/2/3

Multi-item operations

Add multiple new items to end of a sequence

Create two new items within new stacks and add them to the end of a sequence.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]
[
  {
    "type" : "libraryitem",
    "id" : "[LIBRARYITEM-ID-1]"
  },
  {
   "type" : "libraryitem",
   "id" : "[LIBRARYITEM-ID-2]"
  }
]

A PUT will remove all existing stacks in a sequence.

Insert multiple new items into multiple new stacks in a sequence

Create two new items within new stacks and insert into slots 2 and 3. Subsequent stacks shift right.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]/2
[
  {
    "type" : "libraryitem",
    "id" : "[LIBRARYITEM-ID-1]"
  },
  {
   "type" : "libraryitem",
   "id" : "[LIBRARYITEM-ID-2]"
  }
]

A PUT will replace existing stacks.

Insert multiple new items into a single stack in a sequence

Insert two new items into position 3 of the stack in slot 2. Subsequent items shift down.

POST /rest-api/v1/op/sequence/[SEQUENCE-ID]/2/3
[
  {
    "type" : "libraryitem",
    "id" : "[LIBRARYITEM-ID-1]"
  },
  {
   "type" : "libraryitem",
   "id" : "[LIBRARYITEM-ID-2]"
  }
]

A PUT will replace existing items.

Responses

The response to adding a single item will be the item as it appears in the sequence. When adding multiple items the response will be the full updated sequence.

Idempotency warning

The sequence manipulation API is not idempotent. Repeating the same POST or DELETE API call will add or remove additional items from the sequence. The slot and item offsets of items change when items are added or removed at the beginning of the sequence. This means care needs to be taken when performing a series of operations, especially if there is a communication failure, because a retry could result in adding or removing unexpected items.

To safely update a sequence, add the expected sequence version number to the request header X-If-Version-Match. For example:

X-If-Version-Match: 42

With this header, an update will only be performed if the version number matches. If the version number does not match, a 409 error response will be returned. The Sequence Manipulation API automatically increments the version number after each update.