Add, update, or remove dataset episodes

Request

Add or remove episodes, or change the episode versions used by the dataset's draft. This request does not commit the draft.

Add by string ID: An episode not already in the draft uses its latest version. An episode already in the draft keeps its existing episode version and counts as alreadyPresent. Re-adding an episode with a pending removal restores the episode version used by the last committed dataset version.
Add by object reference: The episode must not already be in the draft. Specify version to select an episode version; omit it to use the latest version.
Update: Changes the episode versions used by existing draft members. Omit version to use the latest episode version.
Operation restrictions: An episode in update cannot also appear in add or remove. An episode added as an object cannot also appear in remove. Repeated references to an episode must either all omit version or all specify the same version number.
Duplicate content: New additions with the same recordings, start time, and end time are treated as duplicates. An existing member is retained; otherwise, one duplicate is added. The remaining additions count as alreadyPresent. Version updates retain all members, even when their recordings and time ranges become identical.
Single Primary Site: Every recording of an added or updated episode must be imported, and all of the draft's recordings must be at the same Primary Site. A change that does not follow this rule is rejected. Removals are always allowed.

Security

ApiKey(Required scopes: datasets.update)

Path

idstringrequired

Dataset ID

Bodyapplication/jsonrequired

addArray of any, <= 2000 items(DatasetEpisodeReferenceList)

Episodes to add to the dataset's draft.

updateArray of any, <= 2000 items(DatasetEpisodeReferenceList)

Existing episodes in the dataset's draft whose selected episode versions should change.

removeArray of strings, <= 2000 items(EpisodeIdList)

Episode ids to remove.

Payload

{
  "add": [
    "string"
  ],
  "update": [
    "string"
  ],
  "remove": [
    "string"
  ]
}

Responses

Patch applied

Bodyapplication/json

addedintegerrequired

Number of episodes inserted.

updatedintegerrequired

Number of episodes whose selected version changed in the dataset's draft.

removedintegerrequired

Number of episodes removed from the dataset's draft.

alreadyPresentintegerrequired

Number of episodes in the add request that were not inserted because an equivalent episode was already in the dataset, or appeared in the same request.

Response

{
  "added": 0,
  "updated": 0,
  "removed": 0,
  "alreadyPresent": 0
}