---
title: "Create Flow Segments"
method: POST
path: "/flows/{flowId}/segments"
tags: ["FlowSegments"]
---

# Create Flow Segments

`POST /flows/{flowId}/segments`

Register either a single new Flow Segment or an array of Segments, attaching the Object id given to a point in the Flow timeline.

The Segment may use a newly-written Media Object, or re-use an existing Media Object from another Flow.

For newly-written Media Objects, the client is responsible for ensuring that the Segment written to the TAMS service instance obeys the following restrictions:
  - All samples in the Object SHOULD be used by the Segment.
  - If the Segment does not use all samples in the Object, `object_timerange` MUST be set to the timerange of media in the object, on the Media Object's timeline
  - The timestamps of each sample in the Media Object MUST equal its position on the Flow timeline, OR `ts_offset` MUST be set such that `media_object_ts + ts_offset = segment_ts`
  - The timerange of the Segment MUST NOT overlap any other Segment in the same Flow. The behaviour is undefined if there is an overlap with existing Segments and a service may return a 400 error response.

A service instance SHOULD reject registrations of Flow Segments with a 400 error response if it references a newly created Media Object in the local TAMS storage that was not intended to be used for the Flow.
A service instance SHOULD accept Flow Segments that reference an existing Media Object in the local TAMS storage that was originally created for another Flow.

A service instance MAY support Media Objects that are held in external storage in another TAMS or other media storage system.
The Flow Segment may in that case require the `get_urls` property to provide the information needed by clients to access the Media Object.

The list of instances of an object (and associated `get_urls` entries) can be modified via the [`/objects`](#/operations/GET_objects) endpoints, which provides a mechanism to register new instances of an object.

Clients MAY modify Flow Segments, but this should only be done in exceptional circumstances to correct metadata such as `key_frame_count`, as such operations will likely break the idempotency of Segments.
If a client needs to modify a Flow Segment, then the client SHOULD first delete the existing Segment and then write a new one.
The behaviour is undefined if the Segment exists and the service may return a 400 error response.

For successful creation of all Segments in the request a 201 response should be provided.
If an error is detected when processing a list of Segments then processing should continue to try and process the remaining Segments.
A 200 response should be returned listing the failed Segments.

Clients are expected to decide how to break content into Media Objects, however those Objects SHOULD be large enough to avoid excessive round trip overheads in the underlying store (_e.g._ of the order of several megabytes) and where codecs with temporal re-ordering are used, Object SHOULD contain complete GOPs or decodable units.

For Media Objects that have been re-used from other Flows, the `timerange` MAY specify only part of the duration of the object:
  - The `timerange` field indicates the new Segment's position in the Flow
  - The timerange of the Segment MUST NOT overlap any other Segment in the same Flow.
  - The Flow Segment's `timerange` start and end, once offset by `ts_offset`, MUST be contained entirely within the Media Object's `timerange`

When re-using Media Objects, requests which change object properties (e.g. `key_frame_count`, `object_timerange`, or `init_object_id`) SHOULD be rejected.

If an Object has previously been registered as an initialisation segment (i.e. via `init_object_id`), Service implementations SHOULD reject its use as a media segment (i.e. via `object_id`).
If an Object has previously been registered as a media segment (i.e. via `object_id`), Service implementations SHOULD reject its use as an initialisation segment (i.e. via `init_object_id`).

## Request body

- union
  - Flowsegmentpost — Provides the location and metadata of the media files corresponding to timerange Segments of a Flow.
    - `object_id` string, required — The Object identifier for the Media Object. The `content-type` of the Media Object MUST match the `container` mime-type of the Flow. Service implementations SHOULD reject Objects IDs which have previously been registered as an `init_object_id` on other Flow Segments. i.e. init segments may not be used as media segments.
    - `init_object_id` string — The Object identifier for the initialisation segment Object required to decode the Media Object. The `content-type` of the initialisation segment Object MAY differ from the `container` mime-type of the Flow. This parameter MUST only be set where the media format makes use of initialisation segments. Initialisation Objects SHOULD be re-used where possible. This parameter SHOULD be omitted where the Object `object_id` already exists and is being re-used. Service implementations SHOULD reject Objects IDs which have previously been registered as an `id` on other Flow Segments. i.e. media segments may not be used as init segments.
    - `ts_offset` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `timerange` string, required — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `object_timerange` string — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `last_duration` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `sample_offset` integer — The start of the Segment represented as a count of samples from the start of the Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set. Must be set if the Flow Segment doesn't start at the beginning of the Media Object. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
    - `sample_count` integer — The count of samples in the Segment (which may be fewer than in the Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Must be set if the Flow Segment doesn't use the entire Media Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
    - `get_urls` object[] — A list of URLs to which a GET request can be made to directly retrieve the contents of the Media Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however service instances may sort the list such that the preferred URL is first. `get_urls` should only be used to add uncontrolled URLs. URLs for the provided object_id controlled by the service instance will be populated automatically by the service instance.
      - `url` string, required — A URL to which a GET request can be made to directly retrieve the contents of the Media Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint
      - `label` string, required — Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. Service implementations should reject any requests containing multiple `get_urls` with the same `label`.
    - `key_frame_count` integer — The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point
  - Flowsegmentpost[]
    - `object_id` string, required — The Object identifier for the Media Object. The `content-type` of the Media Object MUST match the `container` mime-type of the Flow. Service implementations SHOULD reject Objects IDs which have previously been registered as an `init_object_id` on other Flow Segments. i.e. init segments may not be used as media segments.
    - `init_object_id` string — The Object identifier for the initialisation segment Object required to decode the Media Object. The `content-type` of the initialisation segment Object MAY differ from the `container` mime-type of the Flow. This parameter MUST only be set where the media format makes use of initialisation segments. Initialisation Objects SHOULD be re-used where possible. This parameter SHOULD be omitted where the Object `object_id` already exists and is being re-used. Service implementations SHOULD reject Objects IDs which have previously been registered as an `id` on other Flow Segments. i.e. media segments may not be used as init segments.
    - `ts_offset` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `timerange` string, required — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `object_timerange` string — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `last_duration` string — A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `sample_offset` integer — The start of the Segment represented as a count of samples from the start of the Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set. Must be set if the Flow Segment doesn't start at the beginning of the Media Object. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
    - `sample_count` integer — The count of samples in the Segment (which may be fewer than in the Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Must be set if the Flow Segment doesn't use the entire Media Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.
    - `get_urls` object[] — A list of URLs to which a GET request can be made to directly retrieve the contents of the Media Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however service instances may sort the list such that the preferred URL is first. `get_urls` should only be used to add uncontrolled URLs. URLs for the provided object_id controlled by the service instance will be populated automatically by the service instance.
      - `url` string, required — A URL to which a GET request can be made to directly retrieve the contents of the Media Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint
      - `label` string, required — Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. Service implementations should reject any requests containing multiple `get_urls` with the same `label`.
    - `key_frame_count` integer — The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point

## Response `200`

Partial success creating Segments returning list of failed Segments.

- Flowsegmentbulkfailure — List of Segments that have failed to register
  - `failed_segments` object[], required — The list of Segments which have failed to register with the service instance
    - `object_id` string, required — The Object ID of the Segment which has failed to register with the service instance
    - `timerange` string — A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note.
    - `error` Error — Provides more information for an error status.
      - `type` string, required — The error type name.
      - `summary` string, required — Summary description of the error and causes.
      - `traceback` string[] — Stack trace leading to error (as a list of strings)
      - `time` string, date-time, required — Time at which the error ocurred, to aid in log correlation

## Other responses

- `201` — created. The flow Segment or list of Segments has been created.
- `400` — Bad request. Invalid Flow Segment JSON or the Flow 'container' is not set.
- `403` — Forbidden. You do not have permission to modify this Flow. It may be marked read-only.
- `404` — The Flow does not exist.

## Changes

- **2026-07-10** `7a9a5cdbb3d2` — 2 info
  - added the new optional request property `oneOf[subschema #1: Flow Segment Post]/init_object_id`
  - added the new optional request property `oneOf[subschema #2]/items/init_object_id`
- **2025-10-21** `4c8d2bfcb854` — 2 breaking, 6 info
  - the request property `oneOf[subschema #1: Flow Segment Post]/get_urls/items/label` became required
  - the request property `oneOf[subschema #2]/items/get_urls/items/label` became required
  - added the new optional request property `oneOf[subschema #1: Flow Segment Post]/object_timerange`
  - added the new optional request property `oneOf[subschema #2]/items/object_timerange`
  - …4 more
- **2025-07-02** `fff531b4534a` — 1 breaking, 1 info
  - removed `#/components/schemas/flowsegment` from the request body `oneOf` list
  - added `#/components/schemas/flowsegmentpost` to the request body `oneOf` list
- **2025-06-11** `e3d4dd57646b` — 1 breaking, 8 warning, 2 info
  - the request's body type/format changed from `object`/`` to ``/``
  - removed the request property `get_urls`
  - removed the request property `key_frame_count`
  - removed the request property `last_duration`
  - …7 more
- …earlier changes not shown

[Full history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/flows/:flowId/segments/post.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)