openapi: 3.1.0
info:
  title: Time-addressable Media Store
  description: |
    The Time-addressable Media Store (TAMS) is used for storing segmented media flows.
    The TAMS consists of a media store for the media flow segment objects and a service providing
    a database index of the flow segments. This document is a specification of the service API.

    See the [bbc/tams](https://github.com/bbc/tams) repository for more background on TAMS.

    **Note**: the examples provided in this specification are for a system which uses a media
    store that provides HTTP URLs for uploading and downloading media objects in buckets. This
    could for example be implemented using an AWS S3 compatible store using presigned URLs or by
    a simple file system storage with an HTTP frontend. Clients should parse the /service endpoint
    and handle the media store type in use appropriately.
  version: '7.0'
  contact:
    name: BBC R&D - Cloud-Fit Production Team
    email: cloudfit-opensource@rd.bbc.co.uk
    url: https://github.com/bbc/tams
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
servers:
- url: http://localhost:4010
  description: Local mock of API
- url: https://example.com/tams/{version}
  description: Example TAMS service
  variables:
    version:
      description: API version
      default: v7.0
security:
- bearer_token_auth: []
- url_token_auth: []
- basic_auth: []
paths:
  /:
    head:
      summary: List Root Endpoints
      description: Return root path headers
      operationId: HEAD_root
      tags:
      - Service
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
    get:
      summary: List Root Endpoints
      description: List of paths available from this API.
      operationId: GET_root
      tags:
      - Service
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                example:
                - service
                - flows
                - sources
                - flow-delete-requests
  /service:
    head:
      summary: Service Information
      description: Return service path headers
      operationId: HEAD_service
      tags:
      - Service
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
    get:
      summary: Service Information
      description: Provide information about the service.
      operationId: GET_service
      tags:
      - Service
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/service'
              example:
                $ref: examples/service-get-200.json
    post:
      summary: Update Service Information
      description: Update the service info.
      operationId: POST_service
      tags:
      - Service
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/service-post.json
            schema:
              $ref: '#/components/schemas/servicepost'
        required: true
      responses:
        '200':
          description: Success. The service info has been updated.
        '400':
          description: Bad request. Invalid service JSON.
  /service/storage-backends:
    head:
      summary: Storage Backend Information
      description: Return storage backends path headers
      operationId: HEAD_storage-backends
      tags:
      - Service
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
    get:
      summary: Storage Backend Information
      description: Provide information about the storage backends available on this service instance. These are populated on deployment of the service instance.
      operationId: GET_storage-backends
      tags:
      - Service
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/storagebackendslist'
              example:
                $ref: examples/storage-backends-get-200.json
  /service/webhooks:
    head:
      summary: List Webhook URLs
      description: Return webhooks path headers
      operationId: HEAD_webhooks
      tags:
      - Webhooks
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
        '404':
          description: Webhooks are not supported by this API implementation
    get:
      summary: List Webhook URLs
      description: |
        Get the list of registered webhook URLs. Implementations SHOULD take steps to avoid displaying URLs to users
        other than those who have suitable permissions (e.g. the owning user).
        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms`
        list on the service endpoint.
      operationId: GET_webhooks
      tags:
      - Webhooks
      responses:
        '200':
          description: Return the list of known webhook URLs. Note that the `api_key_value` will be omitted.
          content:
            application/json:
              example:
              - url: https://hook.example.com
                api_key_name: Authorization
                events:
                - flows/created
                - flows/updated
                - flows/deleted
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/webhook'
        '404':
          description: Webhooks are not supported by this API implementation
    post:
      summary: Register Webhook URL
      description: |
        Register to receive event notifications as webhooks on a specified URL. Webhook messages will conform to the
        format in the `webhooks` section of the API docs, depending on the event type (as defined in the same section).
        Availability of this endpoint is indicated by the name "webhooks" appearing in the `event_stream_mechanisms`
        list on the service endpoint.

        Making a POST request to this endpoint with the same URL, API key name and value but a different list
        of `events` SHOULD update the existing registration. POSTing an empty list of events SHOULD remove the
        registration.

        HTTP requests from the service SHOULD include a `api_key_name` header with the 'api_key_value' value. Clients SHOULD verify this against the value they provided when registering the webhook.

        API implementations MAY partially support event filtering and transformations.
        API implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported.

        API implementations SHOULD consider the security implementations of providing webhooks, and include appropriate
        mitigations against Server Side Request Forgery (SSRF) attacks and similar.
      operationId: POST_webhooks
      tags:
      - Webhooks
      requestBody:
        content:
          application/json:
            example:
              url: https://hook.example.com
              api_key_name: Authorization
              api_key_value: Bearer 21238dksdjqwpqscj9
              events:
              - flows/created
              - flows/updated
            schema:
              $ref: '#/components/schemas/webhookpost'
        required: true
      responses:
        '201':
          description: Success. The webhook has been registered or updated
        '204':
          description: Success. The webhook has been removed
        '400':
          description: Bad request. Invalid parameters or unsupported event filtering or transformation.
        '404':
          description: Webhooks are not supported by this API implementation
  /sources:
    head:
      summary: List Sources
      description: Return Sources path headers
      operationId: HEAD_sources
      tags:
      - Sources
      parameters:
      - name: label
        in: query
        description: Filter on Sources that have the given label.
        schema:
          type: string
      - name: tag.{name}
        in: query
        description: |
          Filter on Sources that have a tag named {name} and with the given value.
          The {name} could contain escaped characters to allow it to be used in a
          URL.
        schema:
          type: string
      - name: tag_exists.{name}
        in: query
        description: |
          Filter on Sources that have a tag named {name} regardless of value. The
          {name} could contain escaped characters to allow it to be used in a
          URL. If set to true then the presence of the tag is filtered for. If set
          to false then its absence is. If left out then no filtering on tag presence
          is performed.
        schema:
          type: boolean
      - name: format
        in: query
        description: Filter on source format.
        schema:
          $ref: '#/components/schemas/contentformat'
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/trait_resource_info_head_400'
    get:
      summary: List Sources
      description: List the Sources registered in the store and their details.
      operationId: GET_sources
      tags:
      - Sources
      parameters:
      - name: label
        in: query
        description: Filter on Sources that have the given label.
        schema:
          type: string
      - name: tag.{name}
        in: query
        description: |
          Filter on Sources that have a tag named {name} and with the given value.
          The {name} could contain escaped characters to allow it to be used in a
          URL.
        schema:
          type: string
      - name: tag_exists.{name}
        in: query
        description: |
          Filter on Sources that have a tag named {name} regardless of value. The
          {name} could contain escaped characters to allow it to be used in a
          URL. If set to true then the presence of the tag is filtered for. If set
          to false then its absence is. If left out then no filtering on tag presence
          is performed.
        schema:
          type: boolean
      - name: format
        in: query
        description: Filter on source format.
        schema:
          $ref: '#/components/schemas/contentformat'
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              example:
                $ref: examples/sources-get-200.json
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/source'
        '400':
          description: Bad request. Invalid query options.
  /sources/{sourceId}:
    parameters:
    - name: sourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The Source identifier.
    head:
      summary: Source Details
      description: Return Source headers
      operationId: HEAD_sources-sourceId
      tags:
      - Sources
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Source Details
      description: Returns Source metadata.
      operationId: GET_sources-sourceId
      tags:
      - Sources
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/source'
              examples:
                basic:
                  summary: Source containing elemental video
                  value:
                    $ref: examples/source-get-200-basic.json
                multi:
                  summary: Multi-essence Source
                  description: Multi-essence Sources collect multiple Sources of different formats under one Source ID.
                  value:
                    $ref: examples/source-get-200-multi.json
        '404':
          description: The requested Source does not exist.
  /sources/{sourceId}/tags:
    parameters:
    - name: sourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The Source identifier.
    head:
      summary: List Source Tags
      description: Return Source tags path headers
      operationId: HEAD_sources-sourceId-tags
      tags:
      - Sources
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
        '404':
          description: The requested Source does not exist.
    get:
      summary: List Source Tags
      description: Returns the Source tags.
      operationId: GET_sources-sourceId-tags
      tags:
      - Sources
      responses:
        '200':
          description: ''
          content:
            application/json:
              example:
                ingested_by: ingest_service_api
              schema:
                $ref: '#/components/schemas/tags'
        '404':
          description: The requested Source does not exist.
  /sources/{sourceId}/tags/{name}:
    parameters:
    - name: name
      in: path
      required: true
      schema:
        type: string
      description: The tag name.
    - name: sourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The Source identifier.
    head:
      summary: Source Tag Value
      description: Return Source tag path headers
      operationId: HEAD_sources-sourceId-tags-name
      tags:
      - Sources
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          description: The requested Source or tag does not exist.
    get:
      summary: Source Tag Value
      description: Return the tag value associated with the tag name.
      operationId: GET_sources-sourceId-tags-name
      tags:
      - Sources
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "ingest_service_api"
              schema:
                type: string
        '404':
          description: The requested Source or tag does not exist.
    put:
      summary: Create or Update Source Tag
      description: Create or update the Source tag
      operationId: PUT_sources-sourceId-tags-name
      tags:
      - Sources
      requestBody:
        content:
          application/json:
            example: |
              "new_value"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The tag has been created or updated.
        '400':
          description: Bad request. Invalid Source tag value.
        '404':
          description: The requested Source does not exist, or the tag name in the path is invalid.
    delete:
      summary: Delete Source Tag
      description: Delete a specific tag on a Source
      operationId: DELETE_sources-sourceId-tags-name
      tags:
      - Sources
      responses:
        '204':
          description: No content. The Source tag has been deleted.
        '404':
          description: The requested Source ID or tag in the path is invalid.
  /sources/{sourceId}/description:
    parameters:
    - name: sourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The Source identifier.
    head:
      summary: Source Description
      description: Return Source description path headers
      operationId: HEAD_sources-sourceId-description
      tags:
      - Sources
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Source Description
      description: Returns the Source description property.
      operationId: GET_sources-sourceId-description
      tags:
      - Sources
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "Big Buck Bunny"
              schema:
                type: string
        '404':
          description: The requested Source does not exist.
    put:
      summary: Create or Update Source Description
      description: Create or update the description property.
      operationId: PUT_sources-sourceId-description
      tags:
      - Sources
      requestBody:
        content:
          application/json:
            example: |
              "Big Buck Bunny Movie"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The description has been created or updated.
        '400':
          description: Bad request. Invalid Source description.
        '404':
          description: The requested Source does not exist.
    delete:
      summary: Delete Source Description
      description: Delete the description property.
      operationId: DELETE_sources-sourceId-description
      tags:
      - Sources
      responses:
        '204':
          description: No content. The Source description property has been deleted.
        '404':
          description: The Source ID in the path is invalid.
  /sources/{sourceId}/label:
    parameters:
    - name: sourceId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The Source identifier.
    head:
      summary: Source Label
      description: Return Source label path headers
      operationId: HEAD_sources-sourceId-label
      tags:
      - Sources
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          description: The requested Source does not exist, or does not have a label set.
    get:
      summary: Source Label
      description: Returns the Source label property.
      operationId: GET_sources-sourceId-label
      tags:
      - Sources
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "Big Buck Bunny"
              schema:
                type: string
        '404':
          description: The requested Source does not exist, or does not have a label set.
    put:
      summary: Create or Update Source Label
      description: Create or update the label property.
      operationId: PUT_sources-sourceId-label
      tags:
      - Sources
      requestBody:
        content:
          application/json:
            example: |
              "Big Buck Bunny Movie"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The label has been created or updated.
        '400':
          description: Bad request. Invalid Source label.
        '404':
          description: The requested Source does not exist.
    delete:
      summary: Delete Source Label
      description: Delete the label property.
      operationId: DELETE_sources-sourceId-label
      tags:
      - Sources
      responses:
        '204':
          description: No content. The Source label property has been deleted.
        '404':
          description: The requested Source ID in the path is invalid.
  /flows:
    head:
      summary: List Flows
      description: Return flows path headers
      operationId: HEAD_flows
      tags:
      - Flows
      parameters:
      - name: source_id
        in: query
        description: Filter on source identifier.
        schema:
          $ref: '#/components/schemas/uuid'
      - name: timerange
        in: query
        description: Filter on flows that overlap the given timerange.
        schema:
          default: _
          $ref: '#/components/schemas/timerange'
      - name: format
        in: query
        description: Filter on flow format.
        schema:
          $ref: '#/components/schemas/contentformat'
      - name: codec
        in: query
        description: Filter on flow codec.
        schema:
          $ref: '#/components/schemas/mimetype'
      - name: label
        in: query
        description: Filter on flows that have the given label.
        schema:
          type: string
      - name: tag.{name}
        in: query
        description: |
          Filter on flows that have a tag named {name} and with the given value.
          The {name} could contain escaped characters to allow it to be used in a
          URL.
        schema:
          type: string
      - name: tag_exists.{name}
        in: query
        description: |
          Filter on flows that have a tag named {name} regardless of value. The
          {name} could contain escaped characters to allow it to be used in a
          URL. If set to true then the presence of the tag is filtered for. If set
          to false then its absence is. If left out then no filtering on tag presence
          is performed.
        schema:
          type: boolean
      - name: frame_width
        in: query
        description: Filter on video flows that have the given frame width.
        schema:
          type: integer
      - name: frame_height
        in: query
        description: Filter on video flows that have the given frame height.
        schema:
          type: integer
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad request. Invalid query options.
    get:
      summary: List Flows
      description: List the flows registered in the store.
      operationId: GET_flows
      tags:
      - Flows
      parameters:
      - name: source_id
        in: query
        description: Filter on source identifier.
        schema:
          $ref: '#/components/schemas/uuid'
      - name: timerange
        in: query
        description: Filter on flows that overlap the given timerange. An empty timerange returns flows with no content.
        schema:
          default: _
          $ref: '#/components/schemas/timerange'
      - name: format
        in: query
        description: Filter on flow format.
        schema:
          $ref: '#/components/schemas/contentformat'
      - name: codec
        in: query
        description: Filter on flow codec.
        schema:
          $ref: '#/components/schemas/mimetype'
      - name: label
        in: query
        description: Filter on flows that have the given label.
        schema:
          type: string
      - name: tag.{name}
        in: query
        description: |
          Filter on flows that have a tag named {name} and with the given value.
          The {name} could contain escaped characters to allow it to be used in a
          URL.
        schema:
          type: string
      - name: tag_exists.{name}
        in: query
        description: |
          Filter on flows that have a tag named {name} regardless of value. The
          {name} could contain escaped characters to allow it to be used in a
          URL. If set to true then the presence of the tag is filtered for. If set
          to false then its absence is. If left out then no filtering on tag presence
          is performed.
        schema:
          type: boolean
      - name: frame_width
        in: query
        description: Filter on video flows that have the given frame width.
        schema:
          type: integer
      - name: frame_height
        in: query
        description: Filter on video flows that have the given frame height.
        schema:
          type: integer
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              example:
                $ref: examples/flows-get-200.json
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/flow'
        '400':
          description: Bad request. Invalid query options.
  /flows/{flowId}:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Details
      description: Return flow path headers
      operationId: HEAD_flows-flowId
      tags:
      - Flows
      parameters:
      - name: include_timerange
        in: query
        description: Include the available segment timerange in the response.
        schema:
          default: false
          type: boolean
      - name: timerange
        in: query
        description: Limit the returned available segment timerange to this timerange.
        schema:
          default: _
          $ref: '#/components/schemas/timerange'
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '400':
          description: Bad request. Invalid query options.
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Details
      description: Returns flow metadata.
      operationId: GET_flows-flowId
      tags:
      - Flows
      parameters:
      - name: include_timerange
        in: query
        description: Include the available segment timerange in the response.
        schema:
          default: false
          type: boolean
      - name: timerange
        in: query
        description: Limit the returned available segment timerange to this timerange.
        schema:
          default: _
          $ref: '#/components/schemas/timerange'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flow'
              examples:
                video:
                  summary: Video Flow - H.264 Codec
                  value:
                    $ref: examples/flow-get-200-video-h264.json
                audio:
                  summary: Audio Flow - AAC Codec
                  value:
                    $ref: examples/flow-get-200-audio-aac.json
                rawvideo:
                  summary: Video Flow - Uncompressed (Quicktime)
                  value:
                    $ref: examples/flow-get-200-video-raw.json
                jpegimage:
                  summary: Image Flow - JPEG Codec
                  value:
                    $ref: examples/flow-get-200-image-jpeg.json
                ttml:
                  summary: Data Flow - TTML
                  description: TAMS can also be used for storing non-AV content such as subtitles or event data
                  value:
                    $ref: examples/flow-get-200-data-ttml.json
                multi:
                  summary: Multi-essence Flow
                  description: Multi-essence Flows are used to collect multiple Flows of different formats under one Flow ID
                  value:
                    $ref: examples/flow-get-200-multi.json
                multi-container-map:
                  summary: Multi-essence Flow with a container map
                  description: |
                    Multi-essence Flows are used to collect multiple Flows of different formats under one Flow ID.
                    The collection has container maps for the audio Flows as there are 2 audio tracks in the container.
                  value:
                    $ref: examples/flow-get-200-multi-container-map.json
                audio-multi:
                  summary: Audio Flow in a multi-essence Flow
                  description: |
                    The audio Flow does not have a container property as the media is accessed via the multi-essence Flow
                  value:
                    $ref: examples/flow-get-200-audio-aac-multi.json
        '404':
          description: The requested flow does not exist.
        '400':
          description: Bad request. Invalid query options.
    put:
      summary: Create or Replace Flow
      description: Create or replace the flow metadata.
      operationId: PUT_flows-flowId
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            examples:
              audio:
                summary: Stereo audio Flow
                value:
                  $ref: examples/flow-put.json
              multi:
                summary: Multi-essence Flow
                value:
                  $ref: examples/flow-put-multi.json
            schema:
              $ref: '#/components/schemas/flow'
        required: true
      responses:
        '201':
          description: The flow has been created.
          content:
            application/json:
              example:
                $ref: examples/flow-put-201.json
              schema:
                $ref: '#/components/schemas/flow'
        '204':
          description: No content. The flow has been updated.
        '400':
          description: Bad request. Invalid flow JSON.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested Flow ID in the path is invalid.
    delete:
      summary: Delete Flow
      description: |
        Deletes the flow and associated segments. If flow segment deletion
        takes too long then this request will return 202 Accepted and the `Location` header will point to a
        Flow Delete Request to monitor deletion progress
      operationId: DELETE_flows-flowId
      tags:
      - Flows
      responses:
        '202':
          description: This request has taken longer than the configured timeout, and will continue asynchronously
          headers:
            Location:
              schema:
                type: string
                example: /flow-delete-request/{request-id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletionrequest'
              example:
                $ref: examples/deletion-request-get-200.json
        '204':
          description: No content. The flow has been deleted and the flow segments have been or will be deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested Flow ID in the path is invalid.
  /flows/{flowId}/tags:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: List Flow Tags
      description: Return flow tags path headers
      operationId: HEAD_flows-flowId-tags
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
        '404':
          description: The requested flow does not exist.
    get:
      summary: List Flow Tags
      description: Returns the flow tags.
      operationId: GET_flows-flowId-tags
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example:
                $ref: examples/flow-tags-get-200.json
              schema:
                $ref: '#/components/schemas/tags'
        '404':
          description: The requested flow does not exist.
  /flows/{flowId}/tags/{name}:
    parameters:
    - name: name
      in: path
      required: true
      schema:
        type: string
      description: The tag name.
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Tag Value
      description: Return flow tag path headers
      operationId: HEAD_flows-flowId-tags-name
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          description: The requested flow or tag does not exist.
    get:
      summary: Flow Tag Value
      description: Return the tag value associated with the tag name.
      operationId: GET_flows-flowId-tags-name
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "full"
              schema:
                type: string
        '404':
          description: The requested flow or tag does not exist.
    put:
      summary: Create or Update Flow Tag
      description: Create or update the tag.
      operationId: PUT_flows-flowId-tags-name
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: |
              "proxy"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The tag has been created or updated.
        '400':
          description: Bad request. Invalid flow tag value.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
    delete:
      summary: Delete Flow Tag
      description: Delete the tag.
      operationId: DELETE_flows-flowId-tags-name
      tags:
      - Flows
      responses:
        '204':
          description: No content. The flow tag has been deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/description:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Description
      description: Return flow description path headers
      operationId: HEAD_flows-flowId-description
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Description
      description: Returns the flow description property.
      operationId: GET_flows-flowId-description
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "video capture"
              schema:
                type: string
        '404':
          description: The requested flow does not exist.
    put:
      summary: Create or Update Flow Description
      description: Create or update the description property.
      operationId: PUT_flows-flowId-description
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: |
              "Big Buck Bunny video-only capture"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The description has been created or updated.
        '400':
          description: Bad request. Invalid flow description.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
    delete:
      summary: Delete Flow Description
      description: Delete the description property.
      operationId: DELETE_flows-flowId-description
      tags:
      - Flows
      responses:
        '204':
          description: No content. The flow description property has been deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/label:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Label
      description: Return Flow label path headers
      operationId: HEAD_flows-flowId-label
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          description: The requested Flow does not exist, or does not have a label set.
    get:
      summary: Flow Label
      description: Returns the Flow label property.
      operationId: GET_flows-flowId-label
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: |
                "Big Buck Bunny"
              schema:
                type: string
        '404':
          description: The requested Flow does not exist, or does not have a label set.
    put:
      summary: Create or Update Flow Label
      description: Create or update the label property.
      operationId: PUT_flows-flowId-label
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: |
              "Big Buck Bunny Movie"
            schema:
              type: string
        required: true
      responses:
        '204':
          description: No content. The label has been created or updated.
        '400':
          description: Bad request. Invalid Flow label.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested Flow does not exist.
    delete:
      summary: Delete Flow Label
      description: Delete the label property.
      operationId: DELETE_flows-flowId-label
      tags:
      - Flows
      responses:
        '204':
          description: No content. The Flow label property has been deleted.
        '404':
          description: The requested Flow ID in the path is invalid.
  /flows/{flowId}/read_only:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Read-Only
      description: Return flow read_only path headers
      operationId: HEAD_flows-flowId-read-only
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Read-Only
      description: Returns the flow read_only property.
      operationId: GET_flows-flowId-read-only
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: true
              schema:
                type: boolean
        '404':
          description: The requested flow does not exist.
    put:
      summary: Set Flow Read-Only
      description: Set the read-only property.
      operationId: PUT_flows-flowId-read-only
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: true
            schema:
              type: boolean
        required: true
      responses:
        '204':
          description: No content. The read_only property has been set to the given value.
        '400':
          description: Bad request. Invalid flow read_only value. Value must be boolean.
        '404':
          description: The requested flow does not exist.
  /flows/{flowId}/flow_collection:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Collection
      description: Returns the flow collection path headers
      operationId: HEAD_flows-flowId-flow-collection
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Collection
      description: Returns the flow collection property.
      operationId: GET_flows-flowId-flow-collection
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example:
                $ref: examples/flow-collection-get-200.json
              schema:
                $ref: '#/components/schemas/flowcollection'
        '404':
          description: The requested flow does not exist.
    put:
      summary: Create or Update Flow Collection
      description: Create or update the flow collection property.
      operationId: PUT_flows-flowId-flow-collection
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/flow-collection-put.json
            schema:
              $ref: '#/components/schemas/flowcollection'
        required: true
      responses:
        '204':
          description: No content. The flow collection has been created or updated.
        '400':
          description: Bad request. Invalid flow collection.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
    delete:
      summary: Delete Flow Collection
      description: Delete the flow collection property.
      operationId: DELETE_flows-flowId-flow-collection
      tags:
      - Flows
      responses:
        '204':
          description: No content. The flow collection property has been deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/max_bit_rate:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Maximum Bit Rate
      description: Returns the flow max bit rate path headers
      operationId: HEAD_flows-flowId-max-bit-rate
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Maximum Bit Rate
      description: Returns the flow max bit rate property.
      operationId: GET_flows-flowId-max-bit-rate
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: 5000
              schema:
                type: integer
                minimum: 0
        '404':
          description: The requested flow does not exist.
    put:
      summary: Create or Update Flow Maximum Bit Rate
      description: Create or update the max bit rate property.
      operationId: PUT_flows-flowId-max-bit-rate
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: 5000
            schema:
              type: integer
              minimum: 0
        required: true
      responses:
        '204':
          description: No content. The max bit rate has been created or updated.
        '400':
          description: Bad request. Invalid flow max bit rate.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
    delete:
      summary: Delete Flow Maximum Bit Rate
      description: Delete the flow max bit rate property.
      operationId: DELETE_flows-flowId-max-bit-rate
      tags:
      - Flows
      responses:
        '204':
          description: No content. The flow max bit rate property has been deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/avg_bit_rate:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: Flow Average Bit Rate
      description: Returns the flow average bit rate path headers
      operationId: HEAD_flows-flowId-avg-bit-rate
      tags:
      - Flows
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Average Bit Rate
      description: Returns the flow average bit rate property.
      operationId: GET_flows-flowId-avg-bit-rate
      tags:
      - Flows
      responses:
        '200':
          description: ''
          content:
            application/json:
              example: 3246
              schema:
                type: integer
                minimum: 0
        '404':
          description: The requested flow does not exist.
    put:
      summary: Create or Update Flow Average Bit Rate
      description: Create or update the average bit rate property.
      operationId: PUT_flows-flowId-avg-bit-rate
      tags:
      - Flows
      requestBody:
        content:
          application/json:
            example: 3246
            schema:
              type: integer
              minimum: 0
        required: true
      responses:
        '204':
          description: No content. The average bit rate has been created or updated.
        '400':
          description: Bad request. Invalid flow avg bit rate.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
    delete:
      summary: Delete Flow Average Bit Rate
      description: Delete the flow average bit rate property.
      operationId: DELETE_flows-flowId-avg-bit-rate
      tags:
      - Flows
      responses:
        '204':
          description: No content. The flow average bit rate property has been deleted.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/segments:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    head:
      summary: List Flow Segments
      description: Return flow segments path headers
      operationId: HEAD_flows-flowId-segments
      tags:
      - FlowSegments
      parameters:
      - name: object_id
        in: query
        description: Filter on object identifier.
        schema:
          type: string
      - name: timerange
        in: query
        description: Return only the results in the timerange specified.
        schema:
          $ref: '#/components/schemas/timerange'
      - name: reverse_order
        in: query
        description: Return segments in reverse time order.
        schema:
          default: false
          type: boolean
      - name: verbose_storage
        in: query
        description: |
          Include storage metadata in `get_urls`.
          When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
        schema:
          default: false
          type: boolean
      - name: accept_get_urls
        in: query
        description: |
          A comma separated list of labels of flow segment `get_urls` to include in the response.
          Omitting `accept_get_urls` will result in no filtering of `get_urls`.
          An empty `accept_get_urls` results in an empty or no `get_urls` in the response.
          Flow segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty.
          Without `get_urls`, the response from the service could be substantially faster if it is not required to
          generate a large number of pre-signed URLs for example.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: string
          pattern: ^([^,]+(,[^,]+)*)?$
      - name: accept_storage_ids
        in: query
        description: |
          A comma separated list of `storage_id`s of flow segment `get_urls` to include in the response.
          Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`.
          Flow segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty.
          A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: string
          pattern: ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(,[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})*$
      - name: presigned
        in: query
        description: |
          If set to `true`, only presigned URLs (i.e. those whos `presigned` property is `true`) will be returned in `get_urls`.
          If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls`.
          If omitted, both presigned and non-presigned URLs will be returned.
          If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to
          generate a large number of pre-signed URLs.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: boolean
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-Timerange:
              description: Identifies the timerange for the returned data set.
              schema:
                $ref: '#/components/schemas/timerange'
            X-Paging-Count:
              description: The number of items in the returned data set.
              schema:
                type: integer
            X-Paging-Reverse-Order:
              description: The items are returned in reverse order.
              schema:
                type: boolean
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '400':
          description: Bad request. Invalid query options.
        '404':
          description: The flow ID in the path is invalid.
    get:
      summary: List Flow Segments
      description: |
        Returns the flow segments.

        The flow segment provides information about the media object. The media store type, which is
        indicated in the /service/storage-backends resource, determines the information that is included to allow the
        flow segment's media object to be downloaded. The examples provided here are for the
        "http_object_store" media store type which MUST include a `get_urls` property that contains the
        HTTP URLs for downloading the media object - server implementations should generate this internally.

        The flow segment may include timing and timerange adjustment information that the client needs to
        apply when extracting the samples from the media object.
        - If `sample_count` is set, the timerange of samples must be `sample_offset` to
         `sample_offset + sample_count` (exclusive). Otherwise, the timerange of samples must be
          `sample_offset` until the end.
        - The sample timestamp in the flow segment (`segment_ts`) is the timestamp in the media object
          (`media_object_ts`) adjusted by `ts_offset`: `segment_ts = media_object_ts + ts_offset`. The
          `segment_ts` should equal the start of the `timerange` for the sample at `sample_offset`.

        Use the pagination options to limit the results to a timerange and/or count. The list of flow
        segments can be empty. A request for segments from a non-existent flow will return an empty
        list, not a 404.

        Note that for codecs with temporal re-ordering, the timerange representes the _presentation_
        timeline, and clients may need to check the `key_frame_count` property and/or read backwards
        from the start of the requested timerange to retrieve enough reference material to start
        decoding.

        When making requests to the provided `get_urls`, clients should include credentials if the provided
        URL is on the same origin as the API itself, akin to the `same-origin` mode in the
        [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode).
      operationId: GET_flows-flowId-segments
      tags:
      - FlowSegments
      parameters:
      - name: object_id
        in: query
        description: Filter on object identifier.
        schema:
          type: string
      - name: timerange
        in: query
        description: Return only the results in the timerange specified.
        schema:
          $ref: '#/components/schemas/timerange'
      - name: reverse_order
        in: query
        description: Return segments in reverse time order.
        schema:
          default: false
          type: boolean
      - name: verbose_storage
        in: query
        description: |
          Include storage metadata in `get_urls`.
          When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls`.
        schema:
          default: false
          type: boolean
      - name: accept_get_urls
        in: query
        description: |
          A comma separated list of labels of flow segment `get_urls` to include in the response.
          Omitting `accept_get_urls` will result in no filtering of `get_urls`.
          An empty `accept_get_urls` results in an empty or no `get_urls` in the response.
          Flow segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty.
          Without `get_urls`, the response from the service could be substantially faster if it is not required to
          generate a large number of pre-signed URLs for example.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: string
          pattern: ^([^,]+(,[^,]+)*)?$
      - name: accept_storage_ids
        in: query
        description: |
          A comma separated list of `storage_id`s of flow segment `get_urls` to include in the response.
          Omitting `accept_storage_ids`, or providing an empty `accept_storage_ids` will result in no filtering of `get_urls`.
          Flow segment `get_urls` with no label or storage ID cannot be filtered for; they will only be returned if `accept_get_urls` is omitted, and `accept_storage_ids` is omitted or empty.
          A full list of available `storage_id`s may be found at the `service/storage-backends` endpoint.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: string
          pattern: ^([0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})(,[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12})*$
      - name: presigned
        in: query
        description: |
          If set to `true`, only presigned URLs (i.e. those whos `presigned` property is `true`) will be returned in `get_urls`.
          If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls`.
          If omitted, both presigned and non-presigned URLs will be returned.
          If `presigned` is set to `false`, the response from the service could be substantially faster if it is not required to
          generate a large number of pre-signed URLs.
          Where multiple filter query parameters are provided, the returned `get_urls` will match all filters.
        schema:
          type: boolean
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-Timerange:
              description: Identifies the timerange for the returned data set.
              schema:
                $ref: '#/components/schemas/timerange'
            X-Paging-Count:
              description: The number of items in the returned data set.
              schema:
                type: integer
            X-Paging-Reverse-Order:
              description: The items are returned in reverse order.
              schema:
                type: boolean
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/flowsegment'
              examples:
                basic:
                  summary: Basic Example
                  value:
                    $ref: examples/flow-segments-get-200.json
                sample_count:
                  summary: Partial Segment
                  description: |
                    This example takes part of an existing segment, offsets it with `ts_offset` and then selects a
                    subset of the samples within using `ts_offset` for the second segment in the sequence.
                  value:
                    $ref: examples/flow-segments-get-200-sample-offset.json
                multiple_urls:
                  summary: Multiple URLs
                  description: |
                    This example shows how the media object for a Flow Segment could be accessed using multiple URLs.
                    Clients are free to choose any of the URLs given (which return identical media objects), however the server has
                    expressed a preference for the "pipeline-a" URLs by putting them first in the list.
                  value:
                    $ref: examples/flow-segments-get-200-multiple-urls.json
        '400':
          description: Bad request. Invalid query options.
        '404':
          description: The flow ID in the path is invalid.
    post:
      summary: Create Flow Segments
      description: "Register either a single new flow segment or an array of segments, attaching the object id given to a point in the flow timeline.\n\nThe segment may use a newly-written object, or re-use an existing object from another flow.\n\nFor newly-written objects, the client is responsible for ensuring that the segment written to the store obeys the following restrictions:\n- All samples in the object SHOULD be used by the segment.\n- The timestamps of each sample in the media object MUST equal its position on the Flow timeline, OR `ts_offset` MUST\n  be set such that `media_object_ts + ts_offset = segment_ts`\n- The timerange of the segment MUST NOT overlap any other segment in the same Flow. The behaviour is\n  undefined if there is an overlap with existing segments and a store may return a 400 error response.\n- The `sample_offset` SHOULD be zero.\n\nA TAMS SHOULD reject registrations of Flow Segments with a 400 error response if it references a newly created media object\n\
        in the local TAMS storage that was not intended to be used for the Flow. A TAMS SHOULD accept Flow Segments that reference an\nexisting media object in the local TAMS storage that was originally created for another Flow.\n\nA TAMS MAY support media objects that are held in external storage in another TAMS or other media storage system. The Flow Segment\nmay in that case require the `get_urls` property to provide the information needed by clients to access the media object.\n\nIf a client needs to modify a Flow segment, e.g. to correct metadata such as the `key_frame_count` or add additional\nURLs to `get_urls`, then the client SHOULD first delete the existing segment and then write a new one. The behaviour is\nundefined if the segment exists and a store may return a 400 error response.\n\nFor successful creation of all segments in the request a 201 response should be provided.  If an error is detected when processing\na list of segments then processing should continue to try and\
        \ process the remaining segments.  A 200 response should be returned \nlisting the failed segments.\n\nClients are expected to decide how to break content into media objects, however those objects SHOULD be large\nenough to avoid excessive round trip overheads in the underlying store (_e.g._ of the order of several megabytes)\nand where codecs with temporal re-ordering are used, object SHOULD contain complete GOPs or decodable units.\n\nFor objects that have been re-used from other flows, the `sample_offset` and `sample_count` MAY be used to\nspecify part of the object to use:\n- The `timerange` field indicates the new segment's position in the flow\n- The sample associated with the start of the `timerange` MUST be the one selected by `sample_offset`\n- Likewise, the sample associated with the end of the `timerange` MUST be the one selected by\n  `sample_offset + sample_count - 1`, unless `timerange` has an exclusive end, in which case it will be\n  `sample_offset + sample_count`.\n\
        - The timerange of the segment MUST NOT overlap any other segment in the same Flow.\n"
      operationId: POST_flows-flowId-segments
      tags:
      - FlowSegments
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/flow-segment-post.json
            schema:
              oneOf:
              - $ref: '#/components/schemas/flowsegmentpost'
              - type: array
                items:
                  $ref: '#/components/schemas/flowsegmentpost'
        required: true
      responses:
        '200':
          description: Partial success creating segments returning list of failed segments.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flowsegmentbulkfailure'
              example:
                $ref: examples/flow-segment-partial-failure.json
        '201':
          description: created. The flow segment or list of segments has been created.
        '400':
          description: Bad request. Invalid flow segment JSON or the flow 'container' is not set.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The flow does not exist.
    delete:
      summary: Delete Flow Segment
      description: |
        Deletes the flow segments. If the deletion takes too long then this request will return 202 Accepted and the `Location` header will point to a
        Flow Delete Request to monitor deletion progress
      operationId: DELETE_flows-flowId-segments
      tags:
      - FlowSegments
      parameters:
      - name: timerange
        in: query
        description: Only delete flow segments that are completely covered by the given timerange.
        schema:
          default: _
          $ref: '#/components/schemas/timerange'
      - name: object_id
        in: query
        description: Filter on object identifier.
        schema:
          type: string
      responses:
        '202':
          description: This request has taken longer than the configured timeout, and will continue asynchronously
          headers:
            Location:
              schema:
                type: string
                example: /flow-delete-request/{request-id}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletionrequest'
              example:
                $ref: examples/deletion-request-get-200.json
        '204':
          description: No content. The flow segments have been or will be deleted.
        '400':
          description: Bad request. Invalid query options.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow ID in the path is invalid.
  /flows/{flowId}/storage:
    parameters:
    - name: flowId
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/uuid'
      description: The flow identifier.
    post:
      summary: Allocate Flow Storage
      description: |
        Allocate storage locations for writing media objects.

        The media store type, which is indicated in the /service resource, determines the information provided
        in the response. The examples and description below are for the "http_object_store" media store type.
        This media store type provides HTTP URLs for uploading and downloading media objects in buckets.

        The response will include a PUT URL that a client uses to upload the media object. The client is expected
        to register the flow segment using the /flows/{flowId}/segments endpoint once the upload is complete.
        Implementations need to handle situations where objects were uploaded but no flow segment was registered
        successfully.

        The response may include PUT URLs for creating buckets for the media objects. These PUT URLs should
        be used before uploading media objects. The object_id associated with each storage location has the
        bucket name as its prefix.

        The response may include PUT URLs for setting the CORS properties for the buckets and media objects.

        When making requests to the provided `put_url`, clients should include credentials if the provided
        URL is on the same origin as the API itself, akin to the `same-origin` mode in the
        [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode).
      operationId: POST_flows-flowId-storage
      tags:
      - MediaStorage
      requestBody:
        content:
          application/json:
            examples:
              limit:
                summary: limit
                value:
                  $ref: examples/flow-storage-post.json
              object_ids:
                summary: object_ids
                value:
                  $ref: examples/flow-storage-post-object_ids.json
            schema:
              $ref: '#/components/schemas/flowstoragepost'
      responses:
        '201':
          description: Storage locations for writing media objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/flowstorage'
              example:
                $ref: examples/flow-storage-post-201.json
        '400':
          description: Bad request. Invalid flow storage request JSON or the flow 'container' is not set. If object_ids supplied, some or all already exist.
        '403':
          description: Forbidden. You do not have permission to modify this flow. It may be marked read-only.
        '404':
          description: The requested flow does not exist.
  /objects/{objectId}:
    head:
      summary: Media Object Information
      description: Return flow references and other information about media objects.
      operationId: HEAD_objects
      tags:
      - Objects
      parameters:
      - name: objectId
        in: path
        description: The media object identifier.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              schema:
                type: string
        '400':
          $ref: '#/components/responses/trait_resource_info_head_400'
        '404':
          description: The requested media object does not exist.
    get:
      summary: Media Object Information
      description: |
        Contains flows that references the media object and other information.

        The paging query parameters and headers are required for the list of flow references in the media object.
        API implementations should return a complete list of flow references within reason and API clients should expect
        paging to happen in some rare cases where a media object is used in many flows.
      operationId: GET_objects
      tags:
      - Objects
      parameters:
      - name: objectId
        in: path
        description: The media object identifier.
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/trait_resource_paged_key'
      - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        '200':
          description: ''
          headers:
            Link:
              description: Provides references to cursors for paging. Only the 'rel' attribute with value 'next' and a link to the next page is currently supported. If 'next' is not present then it is the last page.
              schema:
                type: string
            X-Paging-Limit:
              description: Identifies the current limit being used for paging. This may not match the requested value if the requested value was too high for the implementation
              schema:
                type: integer
            X-Paging-NextKey:
              description: Opaque string that can be supplied to the `page` query parameter to get the next page of results.
              schema:
                type: string
          content:
            application/json:
              example:
                $ref: examples/objects-get-200.json
              schema:
                $ref: '#/components/schemas/object'
        '400':
          description: Bad request. Invalid query options.
        '404':
          description: The requested media object does not exist.
  /flow-delete-requests:
    head:
      summary: List Flow Delete Requests
      description: Return flow-delete-requests path headers
      operationId: HEAD_flow-delete-requests
      tags:
      - FlowDeleteRequests
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_listing_head_200'
    get:
      summary: List Flow Delete Requests
      description: |
        List deletion requests currently being worked on, for monitoring in development.

        This will not necessarily list all requests, nor return a consistent set in any particular order,
        and should not be relied upon by clients. However if there are any requests in the system, it will
        always return at least one.
      operationId: GET_flow-delete-requests
      tags:
      - FlowDeleteRequests
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletionrequestslist'
              example:
                $ref: examples/deletion-requests-get-200.json
  /flow-delete-requests/{request-id}:
    parameters:
    - name: request-id
      in: path
      required: true
      schema:
        type: string
    head:
      summary: Flow Delete Request Details
      description: Return flow delete request path headers
      operationId: HEAD_flow-delete-requests-request-id
      tags:
      - FlowDeleteRequests
      responses:
        '200':
          $ref: '#/components/responses/trait_resource_info_head_200'
        '404':
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Flow Delete Request Details
      description: |
        Get information about a timerange of FlowSegments that are being deleted.

        A deletion request is created when a client DELETEs a long timeranges of segments, which takes longer than
        a single HTTP request. Clients will be redirected here to monitor the request's progress.
      operationId: GET_flow-delete-requests-request-id
      tags:
      - FlowDeleteRequests
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/deletionrequest'
              example:
                $ref: examples/deletion-request-get-200.json
        '404':
          description: The requested flow delete request does not exist.
webhooks:
  flows/created:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Flow Created Notification
              description: Information about a Flow which has been newly created in this store instance
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the new Flow was created
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: flows/created
                event:
                  type: object
                  required:
                  - flow
                  properties:
                    flow:
                      $ref: '#/components/schemas/flow'
  flows/updated:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Flow Updated Notification
              description: Information about a Flow for which the metadata has been modified.
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the Flow was modified
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: flows/updated
                event:
                  type: object
                  required:
                  - flow
                  properties:
                    flow:
                      $ref: '#/components/schemas/flow'
  flows/deleted:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Flow Deleted Notification
              description: Notification that a Flow has been deleted (or scheduled for deletion).
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the Flow was modified
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: flows/deleted
                event:
                  type: object
                  required:
                  - flow_id
                  properties:
                    flow_id:
                      $ref: '#/components/schemas/uuid'
  flows/segments_added:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Flow Segments Added
              description: |
                Notification that new segments have been added to a Flow.
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: flows/segments_added
                event:
                  type: object
                  required:
                  - flow_id
                  - segments
                  properties:
                    flow_id:
                      $ref: '#/components/schemas/uuid'
                    segments:
                      type: array
                      items:
                        $ref: '#/components/schemas/flowsegment'
  flows/segments_deleted:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Flow Segments Deleted
              description: |
                Notification that segments have been deleted from a Flow.
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the most recent segment in the timerange was added (and the message generated)
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: flows/segments_added
                event:
                  type: object
                  required:
                  - flow_id
                  - timerange
                  properties:
                    flow_id:
                      $ref: '#/components/schemas/uuid'
                    timerange:
                      description: The timerange of segments that have been deleted. The timerange MUST intersect with a segment which has been deleted at both start and end (e.g. it cannot start or end in empty space).
                      $ref: '#/components/schemas/timerange'
  sources/created:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Source Created Notification
              description: Information about a Source which has been newly created in this store instance
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the new Source was created
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: sources/created
                event:
                  type: object
                  required:
                  - source
                  properties:
                    source:
                      $ref: '#/components/schemas/source'
  sources/updated:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Source Updated Notification
              description: Information about a Source for which the metadata has been modified.
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the Source was modified
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: sources/updated
                event:
                  type: object
                  required:
                  - source
                  properties:
                    source:
                      $ref: '#/components/schemas/source'
  sources/deleted:
    post:
      security:
      - {}
      requestBody:
        content:
          application/json:
            schema:
              title: Source Deleted Notification
              description: Notification that a Source has been deleted.
              required:
              - event_timestamp
              - event_type
              - event
              properties:
                event_timestamp:
                  description: Timestamp at which the Source was modified
                  type: string
                  format: date-time
                event_type:
                  type: string
                  const: sources/deleted
                event:
                  type: object
                  required:
                  - source_id
                  properties:
                    source_id:
                      $ref: '#/components/schemas/uuid'
components:
  schemas:
    uuid:
      title: UUID
      pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      type: string
    contentformat:
      title: Content Format
      description: Identifies the content format for a flow or source using a URN string.
      enum:
      - urn:x-nmos:format:video
      - urn:x-tam:format:image
      - urn:x-nmos:format:audio
      - urn:x-nmos:format:data
      - urn:x-nmos:format:multi
      type: string
    mimetype:
      title: MIME Type
      pattern: .*/.*
      description: MIME Type string.
      type: string
    deletionrequest:
      type: object
      title: Deletion Request
      description: Describes an ongoing deletion request
      required:
      - id
      - flow_id
      - timerange_to_delete
      - delete_flow
      - status
      properties:
        id:
          description: Deletion Request ID
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        flow_id:
          description: ID of the flow to which the deletion request relates
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        timerange_to_delete:
          description: The timerange of FlowSegments to be deleted in this request, as described by the [TimeRange](../schemas/timerange#top) type
          $ref: '#/components/schemas/timerange'
        timerange_remaining:
          description: The timerange of FlowSegments not yet deleted by this request, as described by the [TimeRange](../schemas/timerange#top) type
          $ref: '#/components/schemas/timerange'
        delete_flow:
          description: Whether the Flow should be deleted once the timerange has been
          type: boolean
        created:
          description: Date/Time when this deletion request was created
          type: string
          format: date-time
        created_by:
          description: A string identifier for the entity that created the deletion request. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
          type: string
        updated:
          description: Date/Time when this deletion request was updated
          type: string
          format: date-time
        expiry:
          description: Date/Time when this deletion request will be deleted
          type: string
          format: date-time
        status:
          description: Status of the delete request
          type: string
          enum:
          - created
          - started
          - done
          - error
        error:
          description: Provides more information for the error status, as described by the [Error](../schemas/error#top) type
          $ref: '#/components/schemas/error'
    deletionrequestslist:
      title: Deletion Requests List
      type: array
      items:
        $ref: '#/components/schemas/deletionrequest'
    flowcollection:
      title: Flow Collection
      type: array
      items:
        type: object
        title: Flow Collection Item
        allOf:
        - $ref: '#/components/schemas/collectionitem'
        - type: object
          properties:
            container_mapping:
              description: Describes the mapping of the Flow essence from this Flow collection's container
              $ref: '#/components/schemas/containermapping'
    flowsegmentbulkfailure:
      title: Failed segments
      description: List of segments that have failed to register
      type: object
      required:
      - failed_segments
      properties:
        failed_segments:
          description: The list of segments which have failed to register with the TAMS API
          type: array
          items:
            type: object
            description: Failed segment details
            required:
            - object_id
            properties:
              object_id:
                description: The object ID of the segment which has failed to register with the TAMS API
                type: string
              timerange:
                description: The timerange of segment that has failed, as described by the [TimeRange](../schemas/timerange#top) type
                $ref: '#/components/schemas/timerange'
              error:
                description: Provides more information for the error status, as described by the [Error](../schemas/error#top) type
                $ref: '#/components/schemas/error'
    flowsegmentpost:
      type: object
      description: Provides the location and metadata of the media files corresponding to timerange segments of a Flow.
      title: Flow Segment
      required:
      - object_id
      - timerange
      properties:
        object_id:
          description: The object store identifier for the media object.
          type: string
        ts_offset:
          description: The timestamp offset between the sample timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative
          $ref: '#/components/schemas/timestamp'
        timerange:
          description: The timerange for the samples contained in the segment. The timerange start is always inclusive. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](../schemas/timerange#top) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline.
          $ref: '#/components/schemas/timerange'
        last_duration:
          description: The difference between the exclusive end of the `timerange` and the last sample timestamp. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative
          $ref: '#/components/schemas/timestamp'
        sample_offset:
          description: 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.
          type: integer
        sample_count:
          description: 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. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples
          type: integer
        get_urls:
          description: A list of URLs to which a GET request can be made to directly retrieve the contents of the segment. This is required by the `http_object_store` media store type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however servers 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.
          type: array
          items:
            type: object
            required:
            - url
            properties:
              url:
                description: A URL to which a GET request can be made to directly retrieve the contents of the segment. Clients should include credentials if the provide URL is on the same origin as the API endpoint
                type: string
              label:
                description: Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.
                type: string
        key_frame_count:
          description: The number of key frames in the segment. This should be set greater than zero when the segment contains key frames that serve as a stream access point
          type: integer
    flowsegment:
      type: object
      description: Provides the location and metadata of the media files corresponding to timerange segments of a Flow.
      title: Flow Segment
      required:
      - object_id
      - timerange
      properties:
        object_id:
          description: The object store identifier for the media object.
          type: string
        ts_offset:
          description: The timestamp offset between the sample timestamps stored in the media file and the corresponding timestamp in the segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative
          $ref: '#/components/schemas/timestamp'
        timerange:
          description: The timerange for the samples contained in the segment. The timerange start is always inclusive. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](../schemas/timerange#top) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline.
          $ref: '#/components/schemas/timerange'
        last_duration:
          description: The difference between the exclusive end of the `timerange` and the last sample timestamp. Format as described by the [Timestamp](../schemas/timestamp#top) type, but cannot be negative
          $ref: '#/components/schemas/timestamp'
        sample_offset:
          description: 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.
          type: integer
        sample_count:
          description: 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. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples
          type: integer
        get_urls:
          description: A list of URLs to which a GET request can be made to directly retrieve the contents of the segment. This is required by the `http_object_store` media store type, which is the only one currently described. Clients may choose any URL in the list and treat the content returned as identical, however servers may sort the list such that the preferred URL is first. Storage backend metadata for controlled URLs should be populated by the TAMS instance based on the storage backend the object copy resides in.
          type: array
          items:
            type: object
            unevaluatedProperties: false
            allOf:
            - $ref: '#/components/schemas/storagebackend'
            - type: object
              required:
              - url
              properties:
                storage_id:
                  description: Storage backend identifier
                  type: string
                  pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
                url:
                  description: A URL to which a GET request can be made to directly retrieve the contents of the segment. Clients should include credentials if the provide URL is on the same origin as the API endpoint
                  type: string
                presigned:
                  description: If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed.
                  type: boolean
                label:
                  description: Label identifying this URL. If the URL is controlled by the service instance, this is the Storage Backend's label. If the URL is uncontrolled, this is the label provided when a client registered the URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter.
                  type: string
                controlled:
                  description: If `true`, this URL is on a storage backend controlled by this service instance. If `false`, this URL is uncontrolled and does not have it's lifecycle managed by this instance. If this parameter is unset, assume `true`.
                  type: boolean
        key_frame_count:
          description: The number of key frames in the segment. This should be set greater than zero when the segment contains key frames that serve as a stream access point
          type: integer
    flowstoragepost:
      title: Flow Storage Post
      description: Post data for the flow storage endpoint
      type: object
      properties:
        limit:
          description: Limit the number of storage segments in each response page. Implementations may specify their own default and maximum for the limit
          type: integer
        object_ids:
          description: Array of object_ids to use. The supplied object_ids must be new and not already in use in this store. A 400 response will be returned if any supplied object_id already exists.
          type: array
          items:
            type: string
        storage_id:
          description: The storage backend to allocate storage in. A storage backend identifier as advertised at the `/service` endpoint. If not set the default, as advertised at the `/service` endpoint, will be used if available. An invalid storage backend identifier will result in a 400 error.
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
      not:
        allOf:
        - required:
          - limit
        - required:
          - object_ids
    flowstorage:
      type: object
      title: Media Bucket Object Store
      description: Gives information on storage for media objects. This schema is for the `http_object_store` media store type which provides URLs for storing media objects in bucket, and is the only store type currently implemented.
      properties:
        pre:
          type: array
          description: Actions that need to be taken before the media object can be written
          items:
            type: object
            description: An action
            required:
            - action
            properties:
              action:
                type: string
                enum:
                - create_bucket
              bucket_id:
                type: string
                description: The name of the bucket that needs to be created
              put_url:
                $ref: '#/components/schemas/httprequest'
              put_cors_url:
                $ref: '#/components/schemas/httprequest'
        media_objects:
          type: array
          description: List of information for identifying and uploading media objects
          items:
            type: object
            description: Information for a media object
            required:
            - object_id
            - put_url
            properties:
              object_id:
                description: The object store identifier for the media object.
                type: string
              put_url:
                $ref: '#/components/schemas/httprequest'
              put_cors_url:
                $ref: '#/components/schemas/httprequest'
      additionalProperties: false
    flow:
      type: object
      description: Describes a Flow
      title: Flow
      oneOf:
      - $ref: '#/components/schemas/flowvideo'
      - $ref: '#/components/schemas/flowaudio'
      - $ref: '#/components/schemas/flowimage'
      - $ref: '#/components/schemas/flowdata'
      - $ref: '#/components/schemas/flowmulti'
    object:
      type: object
      description: Describes a media object in the store.
      title: Object
      required:
      - id
      - referenced_by_flows
      properties:
        id:
          description: The media object identifier.
          type: string
        referenced_by_flows:
          type: array
          description: List of Flows that reference this media object via Flow Segments in this store.
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        first_referenced_by_flow:
          description: The first Flow that had a Flow Segment reference the media object in this store. This Flow is also present in 'referenced_by_flows' if it is still referenced by the Flow. This property is optional and may in some implementations become unset if the Flow no longer references the media object, e.g. because it was deleted.
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    servicepost:
      title: Update Service Info
      description: Post update to the service info
      type: object
      properties:
        name:
          description: The service instance name
          type: string
        description:
          description: The service instance description
          type: string
    service:
      type: object
      description: Provides information about the store service
      title: Service
      required:
      - type
      - api_version
      properties:
        name:
          description: The service instance name
          type: string
        description:
          description: The service instance description
          type: string
        type:
          description: The type identifier for the service. The value must start with 'urn:x-tams:service'
          type: string
        api_version:
          description: The version of the TAMS API specification this deployment implements
          type: string
          pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)$
        service_version:
          description: 'The version of software providing this service. Note: Different implementations and software houses may use different conventions for their version identification. As such, this field is intentionally permissive and intended to be informative only. Implementations should avoid using this field to determine compatibility.'
          type: string
        event_stream_mechanisms:
          type: array
          description: List the types of event stream that this implementation supports
          items:
            $ref: '#/components/schemas/eventstreamcommon'
    source:
      type: object
      description: |-
        Describes a Source: an abstract representation of a piece of media as defined in <https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/2.2._Explanation_-_Source.html>

        Sources may be elemental (and represented directly by a Flow), or may represent a collection of other Sources, e.g. a Source collecting video and audio together.
      title: Source
      required:
      - id
      - format
      properties:
        id:
          description: Source identifier
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        format:
          description: The primary content type URN for the Source.
          type: string
          enum:
          - urn:x-nmos:format:video
          - urn:x-tam:format:image
          - urn:x-nmos:format:audio
          - urn:x-nmos:format:data
          - urn:x-nmos:format:multi
          format: uri
        label:
          description: Freeform string label for the Source
          type: string
        description:
          description: Freeform text describing the Source
          type: string
        created_by:
          description: A string identifier for the entity that created the Source. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
          type: string
        updated_by:
          description: A string identifier for the entity that updated the Source metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
          type: string
        created:
          description: The date-time the Source was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          type: string
          format: date-time
        updated:
          description: The date-time the Source metadata was last updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          type: string
          format: date-time
        tags:
          $ref: '#/components/schemas/tags'
        source_collection:
          type: array
          description: List of Sources that are collected together by this Source. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions.
          items:
            $ref: '#/components/schemas/collectionitem'
        collected_by:
          type: array
          description: Sources that reference this Source to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions.
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
    storagebackendslist:
      type: array
      description: Information about the storage backends available on this service instance.
      items:
        allOf:
        - $ref: '#/components/schemas/storagebackend'
        - required:
          - store_type
          - provider
          - store_product
          - id
        - type: object
          properties:
            id:
              description: Storage backend identifier
              type: string
              pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
            label:
              description: Freeform string label for a storage backend.
              type: string
            default_storage:
              description: If set to `true`, this is the default storage backend. The default storage backend will be used if the client does not specify a storage backend id when requesting the allocation of storage. If this parameter is not set, assume `false`. Instances may either set one storage backend as default, or none - indicating that clients must always specify a storage backend.
              type: boolean
      additionalProperties: false
    tags:
      title: Tags
      description: Key value is a freeform string.
      type: object
      additionalProperties:
        type: string
    timerange:
      title: TimeRange
      description: |
        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.
        * `[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.
      type: string
      pattern: ^(\[|\()?(-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8}))?(_(-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8}))?)?(\]|\))?$
    webhookpost:
      title: Register Webhook
      description: Register to receive updates via webhook
      type: object
      required:
      - url
      - events
      properties:
        url:
          description: The URL to which the API should make HTTP POST requests with event data
          type: string
        api_key_name:
          description: The HTTP header name that is added to the event POST with value 'api_key_value'
          type: string
        api_key_value:
          description: The value that the HTTP header 'api_key_name' will be set to
          type: string
        events:
          description: List of event types to receive
          type: array
          items:
            type: string
        flow_ids:
          description: Limit Flow and Flow Segment events to Flows in the given list of Flow IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        source_ids:
          description: Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        flow_collected_by_ids:
          description: Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        source_collected_by_ids:
          description: Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        accept_get_urls:
          description: List of labels of URLs to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_get_urls` query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.
          type: array
          items:
            type: string
        accept_storage_ids:
          description: List of labels of `storage_id`s to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_storage_ids` query parameter for the /flows/{flowId}/segments API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string.
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        presigned:
          description: Whether to include presigned/non-presigned URLs in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `presigned` query parameter for the /flows/{flowId}/segments API endpoint.
          type: boolean
        verbose_storage:
          description: Whether to include storage metadata in the `get_urls` property in `flows/segments_added` events. This option is the same as the `verbose_storage` query parameter for the /flows/{flowId}/segments API endpoint.
          type: boolean
    webhook:
      title: Register Webhook
      description: Register to receive updates via webhook
      type: object
      required:
      - url
      - events
      properties:
        url:
          description: The URL to which the API should make HTTP POST requests with event data
          type: string
        api_key_name:
          description: The HTTP header name that is added to the event POST
          type: string
        api_key_value:
          description: The value that the HTTP header 'api_key_name' will be set to
          type: string
        events:
          description: List of event types to receive
          type: array
          items:
            type: string
        flow_ids:
          description: Limit Flow and Flow Segment events to Flows in the given list of Flow IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        source_ids:
          description: Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        flow_collected_by_ids:
          description: Limit Flow and Flow Segment events to those with Flow that is collected by a Flow Collection in the given list of Flow Collection IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        source_collected_by_ids:
          description: Limit Flow, Flow Segment and Source events to those with Source that is collected by a Source Collection in the given list of Source Collection IDs
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        accept_get_urls:
          description: List of labels of URLs to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_get_urls` query parameter for the /flows/{flowId}/segments API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string.
          type: array
          items:
            type: string
        accept_storage_ids:
          description: List of labels of `storage_id`s to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_storage_ids` query parameter for the /flows/{flowId}/segments API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string.
          type: array
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        presigned:
          description: Whether to include presigned/non-presigned URLs in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `presigned` query parameter for the /flows/{flowId}/segments API endpoint.
          type: boolean
        verbose_storage:
          description: Whether to include storage metadata in the `get_urls` property in `flows/segments_added` events. This option is the same as the `verbose_storage` query parameter for the /flows/{flowId}/segments API endpoint.
          type: boolean
    collectionitem:
      type: object
      description: Describes how an object (Source or Flow) is collected into another object of the same type
      title: Collection Item
      required:
      - id
      - role
      properties:
        id:
          description: Source or Flow Identifier of the member of this collection. Sources must only collect Sources, and Flows must only collect Flows. Must already be registered in TAMS
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        role:
          description: A human-readable role of the element in this collection (e.g. 'R' to denote a right audio channel in a collection of mono audio Sources)
          type: string
    containermapping:
      type: object
      description: Defines the location of Flow essence data in a container track
      title: Container Mapping
      properties:
        track_index:
          description: A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks
          type: integer
          minimum: 0
        format_track_index:
          description: 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
          type: integer
          minimum: 0
        audio_track:
          description: Mapping for channels in audio tracks to the Flow channels
          type: object
          properties:
            channel_numbers:
              description: Array of (zero-based) container channel numbers in Flow order
              type: array
              minItems: 1
              items:
                type: integer
                minimum: 0
            channel_range:
              description: Inclusive range of (zero-based) container channel numbers
              type: string
              pattern: ^[0-9]+_[0-9]+$
        mp2ts_container:
          description: Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0
          type: object
          properties:
            pid:
              description: The packet ID for the elementary stream packets
              type: integer
        mxf_container:
          description: Mapping to Material Exchange Format containers, SMPTE ST 377-1
          type: object
          properties:
            package_uid:
              description: The package UID. Either a SMPTE UMID URN or UUID URN
              type: string
              pattern: ^urn:smpte:umid:[0-9a-fA-F]{8}(.[0-9a-fA-F]{8}){7}$|^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$
            track_id:
              description: The track ID in the package
              type: integer
        isobmff_container:
          description: Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12
          type: object
          properties:
            track_id:
              description: The track ID
              type: integer
    error:
      description: Provides more information for the error status.
      type: object
      required:
      - type
      - summary
      - time
      properties:
        type:
          description: The error type name.
          type: string
        summary:
          description: Summary description of the error and causes.
          type: string
        traceback:
          description: Stack trace leading to error (as a list of strings)
          type: array
          items:
            type: string
        time:
          description: Time at which the error ocurred, to aid in log correlation
          type: string
          format: date-time
    eventstreamcommon:
      type: object
      description: Describes an event stream mechanism available in this implementation of TAMS
      title: Event Stream Mechanism
      required:
      - name
      properties:
        name:
          description: Name of this type of event stream mechanism. Must be unique. Any name defined in this specification is reserved
          type: string
        docs:
          description: Location (e.g. a URL) at which documentation for this event stream mechanism may be found
          type: string
        config:
          type: object
          description: Configuration options required to make use of this mechanism
    flowaudio:
      type: object
      description: Describes an audio Flow
      title: Audio Flow
      allOf:
      - $ref: '#/components/schemas/flowcore'
      - type: object
        required:
        - format
        - essence_parameters
        - codec
        properties:
          format:
            description: The primary content type URN for the flow.
            type: string
            enum:
            - urn:x-nmos:format:audio
          essence_parameters:
            type: object
            description: Describes the parameters of the essence inside this audio Flow
            title: Audio Flow Essence Parameters
            required:
            - sample_rate
            - channels
            additionalProperties: false
            properties:
              sample_rate:
                description: The fixed number of samples per second.
                type: integer
                exclusiveMinimum: 0
              channels:
                description: The channel count.
                type: integer
                exclusiveMinimum: 0
              bit_depth:
                description: The number of significant bits used to represent the audio sample. The minumum number of bytes then equals `round_up(bit_depth / 8)`. If codec is `audio/x-raw-int` bit_depth must be set. If codec is `audio/x-raw-float` bit_depth must be set to 32 or 64
                type: integer
                exclusiveMinimum: 0
              codec_parameters:
                title: Audio Codec Parameters
                type: object
                required: []
                properties:
                  coded_frame_size:
                    description: The fixed number of samples per coded audio frame.
                    type: integer
                  mp4_oti:
                    description: The MPEG-4 Object Type Identification. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#mpeg-4_audio
                    type: integer
              unc_parameters:
                title: Uncompressed Audio Parameters
                type: object
                required:
                - unc_type
                properties:
                  unc_type:
                    description: The uncompressed audio multi-channel representation type. If codec is `audio/x-raw-int` or `audio/x-raw-float`, unc_type must be set.
                    type: string
                    enum:
                    - interleaved
                    - planar
                    - pairs
    flowdata:
      type: object
      description: Describes a data Flow
      title: Data Flow
      allOf:
      - $ref: '#/components/schemas/flowcore'
      - type: object
        required:
        - format
        - essence_parameters
        - codec
        properties:
          format:
            description: The primary content type URN for the flow.
            type: string
            enum:
            - urn:x-nmos:format:data
          essence_parameters:
            type: object
            description: Describes the parameters of the essence inside this data Flow
            title: Data Flow Essence Parameters
            additionalProperties: false
            properties:
              data_type:
                description: The type of information encoded in the flow, identified using a URN. e.g. The data_type may be urn:x-tams:data:bounding-box, and the codec `application/json`.
                type: string
    flowimage:
      type: object
      description: Describes an still image Flow
      title: Image Flow
      allOf:
      - $ref: '#/components/schemas/flowcore'
      - type: object
        required:
        - format
        - essence_parameters
        - codec
        properties:
          format:
            description: The primary content type URN for the flow.
            type: string
            enum:
            - urn:x-tam:format:image
          essence_parameters:
            type: object
            description: Describes the parameters of the essence inside this image Flow
            title: Image Flow Essence Parameters
            required:
            - frame_width
            - frame_height
            additionalProperties: false
            properties:
              frame_width:
                description: The width of the picture in pixels.
                type: integer
                exclusiveMinimum: 0
              frame_height:
                description: The height of the picture in pixels.
                type: integer
                exclusiveMinimum: 0
              aspect_ratio:
                description: The display aspect ratio. i.e. display_width / display_height
                type: object
                required:
                - numerator
                - denominator
                properties:
                  numerator:
                    description: numerator
                    type: integer
                    exclusiveMinimum: 0
                  denominator:
                    description: denominator
                    type: integer
                    exclusiveMinimum: 0
    flowmulti:
      type: object
      description: Describes a multi-essence Flow
      title: Multi-essence Flow
      allOf:
      - $ref: '#/components/schemas/flowcore'
      - type: object
        required:
        - format
        properties:
          format:
            description: The primary content type URN for the flow.
            type: string
            enum:
            - urn:x-nmos:format:multi
    flowvideo:
      type: object
      description: Describes a video Flow
      title: Video Flow
      allOf:
      - $ref: '#/components/schemas/flowcore'
      - type: object
        required:
        - format
        - essence_parameters
        - codec
        properties:
          format:
            description: The primary content type URN for the flow.
            type: string
            enum:
            - urn:x-nmos:format:video
          essence_parameters:
            type: object
            description: Describes the parameters of the essence inside this video Flow
            title: Video Flow Essence Parameters
            required:
            - frame_width
            - frame_height
            additionalProperties: false
            properties:
              frame_rate:
                description: The fixed number of frames per second. If this parameter is unset, the frame_rate is either unknown or variable.
                type: object
                required:
                - numerator
                properties:
                  numerator:
                    description: numerator
                    type: integer
                    exclusiveMinimum: 0
                  denominator:
                    description: denominator
                    type: integer
                    default: 1
                    exclusiveMinimum: 0
              frame_width:
                description: The width of the picture in pixels.
                type: integer
                exclusiveMinimum: 0
              frame_height:
                description: The height of the picture in pixels.
                type: integer
                exclusiveMinimum: 0
              bit_depth:
                description: The number of significant bits used to represent the video component sample. If codec is `video/raw`, bit_depth must be set.
                type: integer
                exclusiveMinimum: 0
              interlace_mode:
                description: Interlaced video mode for frames in this Flow
                type: string
                enum:
                - progressive
                - interlaced_tff
                - interlaced_bff
                - interlaced_psf
              colorspace:
                description: Colorspace used for the video
                type: string
                enum:
                - BT601
                - BT709
                - BT2020
                - BT2100
              transfer_characteristic:
                description: Transfer characteristic
                type: string
                enum:
                - SDR
                - HLG
                - PQ
              aspect_ratio:
                description: The display aspect ratio. i.e. display_width / display_height
                type: object
                required:
                - numerator
                - denominator
                properties:
                  numerator:
                    description: numerator
                    type: integer
                    exclusiveMinimum: 0
                  denominator:
                    description: denominator
                    type: integer
                    exclusiveMinimum: 0
              pixel_aspect_ratio:
                description: The pixel aspect ratio. This is usually 1:1 (i.e. square pixels) for modern video. Some, usually older, video formats use non-square pixels e.g. some Standard Definition video. This is where that may be indicated.
                type: object
                required:
                - numerator
                - denominator
                properties:
                  numerator:
                    description: numerator
                    type: integer
                    exclusiveMinimum: 0
                  denominator:
                    description: denominator
                    type: integer
                    exclusiveMinimum: 0
              component_type:
                description: Picture component representation.
                type: string
                enum:
                - YCbCr
                - RGB
              horiz_chroma_subs:
                description: Horizontal chroma component sub-sampling. When unc_type is set to a YUV type, horiz_chroma_subs must be set.
                type: integer
                exclusiveMinimum: 0
              vert_chroma_subs:
                description: Vertical chroma component sub-sampling. When unc_type is set to a YUV type, vert_chroma_subs must be set.
                type: integer
                exclusiveMinimum: 0
              unc_parameters:
                type: object
                title: Uncompressed Video Parameters
                required:
                - unc_type
                properties:
                  unc_type:
                    description: Uncompressed picture packing type. If codec is `video/raw`, unc_type must be set.
                    type: string
                    enum:
                    - planar
                    - YUYV
                    - UYVY
                    - AYUV
                    - v210
                    - v216
                    - RGB
                    - RGBx
                    - xRGB
                    - BGRx
                    - xBGR
                    - RGBA
                    - ARGB
                    - BGRA
                    - ABGR
                    - alpha
              avc_parameters:
                type: object
                title: AVC Codec Parameters
                required:
                - profile
                - level
                - flags
                properties:
                  profile:
                    description: AVC / H.264 profile byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
                    type: integer
                  level:
                    description: AVC / H.264 level byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
                    type: integer
                  flags:
                    description: AVC / H.264 flags byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter
                    type: integer
    httprequest:
      type: object
      title: HTTP Request
      description: Gives information on a particular http request a client should perform
      required:
      - url
      properties:
        url:
          description: The URL to make the request to
          type: string
        body:
          description: The text of the body which needs to be included in the request
          type: string
        content-type:
          description: The content type which must be used
          type: string
        headers:
          description: Additional headers that should be included
          type: object
          additionalProperties:
            type: string
      additionalProperties: true
    storagebackend:
      type: object
      description: Provides technical, and logic metadata about a storage backend
      title: Storage Backend
      properties:
        store_type:
          description: The generic store type. Used to identify the required workflow for reading and writing media. Any `store_product` should be compatible, as much is required for basic interoperability between TAMS implementations, with their associated generic `store_type`.
          type: string
          enum:
          - http_object_store
        provider:
          description: The cloud (or other) provider of the storage
          type: string
        region:
          description: The region in the cloud this storage backend resides
          type: string
        availability_zone:
          description: The availability zone in the cloud region this storage backend resides. Note that many cloud providers randomize availability zone identifiers such that they are consistent within a cloud account, but not necessarily between accounts. Caution should be exercised when using this parameter.
          type: string
        store_product:
          description: The storage product name.
          type: string
    timestamp:
      title: Timestamp
      description: |
        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.
      type: string
      pattern: ^-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8})$
    flowcore:
      type: object
      description: Describes a Flow (common properties to all Flows, imported by type-specific specifications)
      title: Flow Core
      required:
      - id
      - source_id
      properties:
        id:
          description: Flow identifier
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        source_id:
          description: Source identifier
          type: string
          pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        label:
          description: Freeform string label for the flow
          type: string
        description:
          description: Freeform text describing the flow
          type: string
        created_by:
          description: A string identifier for the entity that created the flow. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
          type: string
        updated_by:
          description: A string identifier for the entity that updated the flow metadata most recently. Implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations.
          type: string
        tags:
          $ref: '#/components/schemas/tags'
        metadata_version:
          description: A change to the flow metadata, not including metadata_version, last_update or segments, results in a new version. If the metadata_version for flow instances is identical then the metadata is identical.
          type: string
        generation:
          description: An indication of how many lossy encodings the flow content has been through. A flow with a higher generation may contain less of the original information than a flow with a lower generation.
          type: integer
          minimum: 0
        created:
          description: The date-time the flow was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          type: string
          format: date-time
        metadata_updated:
          description: The date-time the flow metadata was updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          type: string
          format: date-time
        segments_updated:
          description: The date-time the flow segments were updated in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          type: string
          format: date-time
        read_only:
          description: If set to 'true', implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), Flow Segments and media objects
          type: boolean
        codec:
          description: A MIME type identification of the (lossy or lossless) coding used for the flow content.
          type: string
          pattern: ^[^\s/]+/[^\s/]+$
        container:
          description: The container MIME type for flow segments.
          type: string
          pattern: ^[^\s/]+/[^\s/]+$
        avg_bit_rate:
          description: The average bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
          type: integer
          minimum: 0
        max_bit_rate:
          description: The maximum bit rate of the flow segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote.
          type: integer
          minimum: 0
        segment_duration:
          description: The target flow segment duration in seconds. The duration for each segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes.
          type: object
          required:
          - numerator
          properties:
            numerator:
              description: numerator
              type: integer
              exclusiveMinimum: 0
            denominator:
              description: denominator
              type: integer
              default: 1
              exclusiveMinimum: 0
        timerange:
          description: The timerange of samples available in the flow, as described by the [TimeRange](../schemas/timerange#top) type
          $ref: '#/components/schemas/timerange'
        flow_collection:
          description: List of Flows that are collected together by this Flow.
          $ref: '#/components/schemas/flowcollection'
        collected_by:
          type: array
          description: Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally
          items:
            type: string
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
        container_mapping:
          description: Describes the mapping of the Flow essence from the this Flow's container
          $ref: '#/components/schemas/containermapping'
  responses:
    trait_resource_listing_head_200:
      description: ''
      content:
        application/json:
          schema:
            type: string
    trait_resource_info_head_200:
      description: ''
      content:
        application/json:
          schema:
            type: string
    trait_resource_info_head_400:
      description: Bad request. Query parameters are invalid.
    trait_resource_info_head_404:
      description: Resource was not found.
  parameters:
    trait_paged_limit:
      name: limit
      in: query
      description: Restrict the response to the specified number of results. Implementations may specify their own default and maximum for the limit
      schema:
        type: integer
    trait_resource_paged_key:
      name: page
      in: query
      description: Opaque string used by backend to access a specific page of results. Clients should read the next URL from the `Link` header returned with responses, or use value of the returned X-Paging-NextKey header. If not supplied, the first page is accessed. Implementations should ensure a consistent sort order is applied to pages of results.
      schema:
        type: string
  securitySchemes:
    basic_auth:
      type: http
      scheme: basic
      description: |
        HTTP basic authentication using a username and password.

        This option should only be used in constrained cases where Bearer tokens are impractical, since the password is
        intrinsically long-lived, and managing user credentials across systems is difficult compared to using
        centralised auth (e.g. via OAuth2) with Bearer tokens
    bearer_token_auth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: |
        HTTP bearer token authentication.

        The method through which a client should acquire a bearer token is assumed to be an OAuth2 grant (either the
        Authorization Code or Client Credentials grant), however the OpenAPI `OAuth Flow` object cannot be used because
        it requires that the relevant URLs are known in advance.

        Clients should provide options to allow one (or both) grant types to be configured, as appropriate.

        Where tokens are not JWTs, or are acquired through some other mechanism, the API key method should be used
        instead.
    url_token_auth:
      type: apiKey
      name: access_token
      in: query
      description: |
        URL token authentication.

        The method through which a client should acquire the token is not specified: it is assumed this takes place in
        another way, and a TAMS client may well be passed a URL to a store including the token.

        Clients should retain the token in the `access_token` query string parameter, and use it for subsequent store
        requests in the same session.
tags:
- name: Service
  description: The service root and documentation about the service itself
- name: Sources
  description: |
    The ephemeral concept of an individual piece of media without being rendered to a specific encoding/packaging.
  externalDocs:
    url: https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/2.2._Explanation_-_Source.html
- name: Flows
  description: |
    Sources which have been 'rendered' to a specific encoding/packaging format.
  externalDocs:
    url: https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/2.3._Explanation_-_Flow.html
- name: FlowSegments
  description: |
    A timerange segment of a Flow that references a media object in the object store.
- name: Objects
  description: The object in the object store that contains the media essence.
- name: MediaStorage
  description: The system that stores the media objects referenced by flow segments.
- name: FlowDeleteRequests
  description: Resource for monitoring long running deletion of flows and flow segments.
- name: Webhooks
  description: Configures webhooks to deliver notifications externally. Optional, and may not be implemented