Update an episode

Request

Update an episode and return the resulting version. Effective changes create a version. If nothing changes, the current version is returned.

Security

ApiKey(Required scopes: episodes.update)

Path

idstringrequired

Episode ID

Bodyapplication/jsonrequired

appliesToVersioninteger, [ 1 .. 2147483647 ]

Require this current episode version. Omit to update the latest version.

startTimestring, (date-time)

Inclusive start of the episode window, with up to nanosecond precision.

endTimestring, (date-time)

Inclusive end of the episode window, with up to nanosecond precision. Must not be before startTime. Equal times describe a single instant.

recordingsobject

Add or remove recording display IDs from this episode. After the change, all of the episode's recordings must be imported to the same Primary Site.

propertiesobject(EpisodePropertyPatch)

Merge the supplied keys into the current version's properties. Omitted keys retain their values. Set a key to null to remove its assignment. An empty object makes no changes. Previous episode versions retain their property values.

Payload

{
  "appliesToVersion": 1,
  "startTime": "2019-08-24T14:15:22Z",
  "endTime": "2019-08-24T14:15:22Z",
  "recordings": {
    "add": [ … ],
    "remove": [ … ]
  },
  "properties": {
    "property1": "string",
    "property2": "string"
  }
}

Responses

The episode at the resulting version

Bodyapplication/json

versioninteger, >= 1required

The episode version represented by this response.

latestVersioninteger, >= 1required

The episode's latest version at the time of this read.

propertiesobject(EpisodeProperties)

Custom properties at the selected version. Returned only with include=properties.

creationContextobject or null(EpisodeCreationContext)

Original creation context. Always present when fetching an episode by ID; present on list responses only with ?include=creationContext.

idstringrequired

ID of the episode.

projectIdstringrequired

ID of the project the episode belongs to.

startTimestring, (date-time)required

Inclusive start of the episode window, with up to nanosecond precision.

endTimestring, (date-time)required

Inclusive end of the episode window, with up to nanosecond precision. Equal to startTime for a single instant.

recordingsArray of objects

Member recordings. Present only when the request includes ?include=recordings.

hasMissingRecordingsboolean

Whether any member recording has no data at a Primary Site. Returned by episode endpoints only with include=recordings. Dataset endpoints report this on the containing dataset entry instead.

creatorOrgMemberIdstring or null

ID of the org member who created the episode. Null when the episode was created via API-key auth (in which case creatorApiKeyId is set).

creatorApiKeyIdstring or null

ID of the API key that created the episode. Null when the episode was created via session auth (in which case creatorOrgMemberId is set).

createdAtstring, (date-time)required

Timestamp when the episode was created.

Response

{
  "version": 1,
  "latestVersion": 1,
  "properties": {
    "property1": "string",
    "property2": "string"
  },
  "creationContext": {
    "version": 1,
    "basis": { … },
    "derivedFromEpisodeId": "string",
    "search": { … }
  },
  "id": "string",
  "projectId": "string",
  "startTime": "2019-08-24T14:15:22Z",
  "endTime": "2019-08-24T14:15:22Z",
  "recordings": [
    { … }
  ],
  "hasMissingRecordings": true,
  "creatorOrgMemberId": "string",
  "creatorApiKeyId": "string",
  "createdAt": "2019-08-24T14:15:22Z"
}