External episodes¶

media.episodes.external

media.episodes.external covers creating and updating episodes from an external source. An access control system or external analyzer sends the event directly to central using the stream name.

Creation¶

POST /central/api-v4/episodes stores an episode directly in PostgreSQL. The stream must exist and have episode retention enabled. Locating or waiting for its assigned streamer is unnecessary.

Initial creation returns 201. A replay with the same (media, opened_at, details.type) returns 200 with the original ID and leaves the data unchanged. Custom episodes use the literal custom in the key. Central assigns episode_id and updated_at.

Annotations and search¶

PATCH /central/api-v4/episodes/{episode_id}/meta updates arbitrary external JSON using JSON Merge Patch. Harvesting preserves this field. Unset meta is omitted from the episode JSON.

The JSON meta filter goes in the history request query string and searches for the specified structure before the page limit. Writing requires management write access; a play token grants reading. See the complete curl example in Create, annotate and search in Optic.