---
title: "Create or Update Flow Collection"
method: PUT
path: "/flows/{flowId}/flow_collection"
tags: ["Flows"]
---

# Create or Update Flow Collection

`PUT /flows/{flowId}/flow_collection`

Create or update the Flow collection property. An ordered list of Flows that are collected together by this Flow.

Service implementations SHOULD verify that Flow metadata is compatible with the associated Source.
Service implementations MAY accept modification/addition of parameters, and reflect such changes in the Source, where it will not bring any Flows of the Source into conflict.
Where metadata would result in any Flow of the Source coming into conflict, the request SHOULD be rejected with a 400 response.

## Request body

- object[] — Describes how Flows are collected into another Flow. Note that this is an ordered list.
  - `id` string, required — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562)
  - `role` string — The purpose of this element in the collection, primarily intended to be human-readable.
  - `container_mapping` Containermapping — Defines the location of Flow essence data in a container track
    - `track_index` integer — A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
    - `format_track_index` integer — A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format
    - `audio_track` object — Mapping for channels in audio tracks to the Flow channels
      - `channel_numbers` integer[] — Array of (zero-based) container channel numbers in Flow order
      - `channel_range` string — Inclusive range of (zero-based) container channel numbers
    - `mp2ts_container` object — Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
      - `pid` integer — The packet ID for the elementary stream packets
    - `mxf_container` object — Mapping to Material Exchange Format containers, SMPTE ST 377-1
      - `package_uid` string — The package UID. Either a SMPTE UMID URN or UUID URN
      - `track_id` integer — The track ID in the package
    - `isobmff_container` object — Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
      - `track_id` integer — The track ID

## Response `204`

No content. The Flow collection has been created or updated.

## Other responses

- `400` — Bad request. Invalid Flow collection.
- `403` — Forbidden. You do not have permission to modify this Flow. It may be marked read-only.
- `404` — The requested Flow does not exist.

## Changes

- **2026-08-25** `eb3977b33601` — 1 info
  - the request property `items/allOf[subschema #1: Collection Item]/role` became optional
- **2025-07-02** `fff531b4534a` — 1 breaking, 3 warning
  - added `#/components/schemas/collectionitem, subschema #2` to the `items/` request property `allOf` list
  - removed the request property `items/container_mapping`
  - removed the request property `items/id`
  - removed the request property `items/role`
- **2025-04-24** `b01aaf8cffe2` — 2 breaking, 1 warning, 1 info
  - added the new required request property `items/id`
  - added the new required request property `items/role`
  - removed `#/components/schemas/collectionitem, subschema #2` from the `items/` request property `allOf` list
  - added the new optional request property `items/container_mapping`

[Change history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/flows/:flowId/flow_collection/put.md)

---

[API](https://skmtc.dev/aws-samples/apis/time-addressable-media-store.md) · [All operations](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aws-samples/time-addressable-media-store/revisions/eb3977b33601/schema)