TimeAddressableMediaStore.yaml

#
# Copyright 2023 British Broadcasting Corporation
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
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 one or more Storage Backends 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 Storage Backend that provides HTTP URLs for uploading and downloading 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](#/operations/GET_service) endpoint and handle the Storage Backend type in use appropriately.
  version: "8.2"
  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: v8.2
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: schemas/service.json
              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: schemas/service-post.json
        required: true
      responses:
        "200":
          description: Success. The service info has been updated.
        "400":
          description: Bad request. Invalid service JSON.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
  /service/storage-backends:
    head:
      summary: Storage Backend Information
      description: Return storage backends path headers
      operationId: HEAD_storage-backends
      tags:
        - Service
      parameters:
        - name: tag.{name}
          in: query
          description: |
            Filter on Storage Backends that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Storage Backends that have a tag named {name} regardless of value.
            The {name} MUST be URL encoded where special characters are present.
            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: reverse_order
          in: query
          description: Return Storage Backends in reverse-alphabetical order of their `label`.
          schema:
            default: false
            type: boolean
        - $ref: '#/components/parameters/trait_resource_paged_key'
        - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        "200":
          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 service implementation
              schema:
                type: integer
            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
          $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.

        Storage Backends are sorted in alphabetical order of their `label` by default.
        For resources where `label` is unset, `id` shall be used.
        Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
      operationId: GET_storage-backends
      tags:
        - Service
      parameters:
        - name: tag.{name}
          in: query
          description: |
            Filter on Storage Backends that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Storage Backends that have a tag named {name} regardless of value.
            The {name} MUST be URL encoded where special characters are present.
            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: reverse_order
          in: query
          description: Return Storage Backends in reverse-alphabetical order of their `label`.
          schema:
            default: false
            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 service implementation
              schema:
                type: integer
            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:
                $ref: schemas/storage-backends-list.json
              example:
                $ref: examples/storage-backends-get-200.json
  /service/profiles:
    head:
      summary: Profile Backend Information
      description: Return Profile headers
      operationId: HEAD_profiles
      tags:
        - Profiles
      parameters:
        - name: format
          in: query
          description: Filter on Profile format. Only single-essence formats are supported.
          schema:
            title: Profile Content Format
            description: Identifies the content format for a Profile using a URN string. The multi format is not applicable to Profiles.
            type: string
            format: uri
            enum:
              - urn:x-nmos:format:video
              - urn:x-tam:format:image
              - urn:x-nmos:format:audio
              - urn:x-nmos:format:data
        - name: codec
          in: query
          description: Filter on Profile codec.
          schema:
            $ref: 'schemas/mime-type.json'
        - name: label
          in: query
          description: Filter on Profiles that have the given label.
          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":
          description: Bad request. Invalid query options.
    get:
      summary: Profile Backend Information
      description: List of Profiles supported by the store instance for use when creating flows.
      operationId: GET_profiles
      tags:
        - Profiles
      parameters:
        - name: format
          in: query
          description: Filter on Profile format.
          schema:
            $ref: 'schemas/content-format.json'
        - name: codec
          in: query
          description: Filter on Profile codec.
          schema:
            $ref: 'schemas/mime-type.json'
        - name: label
          in: query
          description: Filter on Profiles that have the given label.
          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/profiles-get-200.json
              schema:
                type: array
                items:
                  $ref: "schemas/profile.json"
        "400":
          description: Bad request. Invalid query options.
  /service/profiles/{profileId}:
    parameters:
      - name: profileId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        description: The Profile identifier.
    head:
      summary: Profile Details
      description: Return Profile path headers
      operationId: HEAD_profiles-profileId
      tags:
        - Profiles
      responses:
        "200":
          $ref: '#/components/responses/trait_resource_info_head_200'
        "404":
          $ref: '#/components/responses/trait_resource_info_head_404'
    get:
      summary: Profile Details
      description: Returns Profile metadata.
      operationId: GET_profiles-profileId
      tags:
        - Profiles
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: schemas/profile.json
              examples:
                video-h264:
                  summary: h264 TS Video Profile
                  externalValue: examples/profile-get-200-video-h264.json
                video-h264-mxf:
                  summary: h264 MXF Video Profile
                  externalValue: examples/profile-get-200-video-h264-mxf.json
                jpegimage:
                  summary: Image Profile
                  externalValue: examples/profile-get-200-image.json
        "404":
          description: The requested profile does not exist.
    post:
      summary: Create Profile
      description: "Create a new Profile to be used when creating flows with the matching metadata.  \n\nServices MUST reject requests that would update an existing Profile as this would mean it no longer matches flows that have already been created using it.\nIf a change to a Profile is required then a new Profile should be created with the updated information and new flows reference this new Profile.  \n\nAttempting to update an existing profiles should return a 400 error.\n\nTags can be created at the Profile level to hold information about the Profile itself.  \nThese do not form part of the flow that is created.  \nThese are tag/value format and could be used for tasks such as version tracking or holding encoding parameters.\n"
      operationId: POST_profiles-profileId
      tags:
        - Profiles
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/profile-put.json
            schema:
              $ref: schemas/profile.json
        required: true
      responses:
        "201":
          description: The Profile has been created.
          content:
            application/json:
              example:
                $ref: examples/profile-post-201.json
              schema:
                $ref: schemas/profile.json
        "400":
          description: Bad request. Invalid Profile JSON or Profile already exists.
        "404":
          description: The requested Profile ID in the path is invalid.
  /service/webhooks:
    head:
      summary: List Webhook URLs
      description: Return webhooks path headers
      operationId: HEAD_webhooks
      tags:
        - Webhooks
      parameters:
        - name: reverse_order
          in: query
          description: Return Webhooks in reverse-alphabetical order of their `url`.
          schema:
            default: false
            type: boolean
        - name: tag.{name}
          in: query
          description: |
            Filter on webhooks that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on webhooks that have a tag named {name} regardless of value.
            The {name} MUST be URL encoded where special characters are present.
            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
        - $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-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
        "404":
          description: "Webhooks are not supported by this service implementation"
    get:
      summary: List Webhook URLs
      description: |
        Get the list of registered webhook URLs.
        Service 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](#/operations/GET_service) endpoint.

        Webhooks are sorted in alphabetical order of their `url` by default.
      operationId: GET_webhooks
      tags:
        - Webhooks
      parameters:
        - name: reverse_order
          in: query
          description: Return Webhooks in reverse-alphabetical order of their `url`.
          schema:
            default: false
            type: boolean
        - name: tag.{name}
          in: query
          description: |
            Filter on webhooks that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on webhooks that have a tag named {name} regardless of value.
            The {name} MUST be URL encoded where special characters are present.
            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
        - $ref: '#/components/parameters/trait_resource_paged_key'
        - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        "200":
          description: Return the list of known webhook URLs.
          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-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:
              example:
                $ref: "examples/webhook-get-200-list.json"
              schema:
                type: array
                items:
                  $ref: "schemas/webhook-get.json"
        "404":
          description: "Webhooks are not supported by this API implementation"
    post:
      summary: Register webhook details
      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.

        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. API implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. This may take the form of RBAC, or ABAC.
      operationId: POST_webhooks
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            example:
              $ref: "examples/webhook-post.json"
            schema:
              $ref: schemas/webhook-post.json
        required: true
      responses:
        "201":
          description: Success. The webhook has been registered.
          content:
            application/json:
              example:
                $ref: "examples/webhook-get-200.json"
              schema:
                $ref: schemas/webhook-get.json
        "400":
          description: Bad request. Invalid parameters or unsupported event filtering or transformation.
        "404":
          description: Webhooks are not supported by this service implementation
  /service/webhooks/{webhookId}:
    parameters:
      - name: webhookId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        description: The Webhook identifier.
    head:
      summary: Webhook details
      description: Return webhook path headers
      operationId: HEAD_webhooks-webhookId
      tags:
        - Webhooks
      responses:
        "200":
          $ref: '#/components/responses/trait_resource_listing_head_200'
        "404":
          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
    get:
      summary: Webhook details
      description: |
        Get the details of a webhook. Service 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`](#/operations/GET_service) endpoint.
      operationId: GET_webhooks-webhookId
      tags:
        - Webhooks
      responses:
        "200":
          description: Return the webhook details.
          content:
            application/json:
              example:
                $ref: "examples/webhook-get-200.json"
              schema:
                $ref: "schemas/webhook-get.json"
        "404":
          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
    put:
      summary: Update webhook details
      description: "Update the configuration of an existing webhook.\n\nWebhook 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).\nAvailability of this endpoint is indicated by the name \"webhooks\" appearing in the `event_stream_mechanisms` list on the [`/service`](#/operations/GET_service) endpoint.\n\nHTTP events sent by the service to a client webhook's endpoint SHOULD include a `api_key_name` header with the 'api_key_value' value.\nClients SHOULD verify this against the value they provided when registering the webhook.\n\nService implementations MAY partially support event filtering and transformations.\nService implementations SHALL return a 400 response code if the filtering or transformation specified in the request is not supported.\n\nService implementations SHOULD consider the security implications of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar.\nService implementations SHOULD take appropriate steps to authorize the modification of existing webhooks. \nThis may take the form of RBAC, or ABAC.\n"
      operationId: PUT_webhooks
      tags:
        - Webhooks
      requestBody:
        content:
          application/json:
            example:
              $ref: "examples/webhook-put.json"
            schema:
              $ref: schemas/webhook-put.json
        required: true
      responses:
        "201":
          description: Success. The webhook has been updated
          content:
            application/json:
              example:
                $ref: "examples/webhook-get-200.json"
              schema:
                $ref: schemas/webhook-get.json
        "400":
          description: Bad request. Invalid parameters or unsupported event filtering or transformation.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "404":
          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service implementation
    delete:
      summary: Delete Webhook
      description: "Deletes the webhook. \nAvailability of this endpoint is indicated by the name \"webhooks\" appearing in the `event_stream_mechanisms` list on the service endpoint.\n\nService implementations SHOULD consider the security implementations of providing webhooks, and include appropriate mitigations against Server Side Request Forgery (SSRF) attacks and similar. \nService implementations SHOULD take appropriate steps to authorize the deleting of webhooks. \nThis may take the form of RBAC, or ABAC.\n"
      operationId: DELETE_webhooks-webhookId
      tags:
        - Webhooks
      responses:
        "204":
          description: No content. The webhook has been deleted.
        "403":
          description: Forbidden. You do not have permission to modify this webhook.
        "404":
          description: The requested Webhook ID in the path is invalid, or Webhooks are not supported by this service 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: reverse_order
          in: query
          description: Return Sources in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Sources by.
            `created` and `updated` sort most recent first by default.
            `label` sorts alphabetically by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - updated
              - label
        - name: tag.{name}
          in: query
          description: |
            Filter on Sources that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Sources that have a tag named {name} regardless of value.
            {name} MUST be URL encoded where special characters are present.
            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: 'schemas/content-format.json'
        - name: collected_by_ids
          in: query
          description: |
            Filter on Sources by the Source Collection(s) that collect them, given as a comma-separated list of Source IDs.
            Returns Sources whose `collected_by` includes at least one of the given Source IDs.
            An empty value (`collected_by_ids=`) returns only Sources that are not collected by any Source, i.e. top-level Sources with no `collected_by` value.
          schema:
            $ref: 'schemas/uuid-list-empty.json'
        - $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 service implementation
              schema:
                type: integer
            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":
          $ref: '#/components/responses/trait_resource_info_head_400'
    get:
      summary: List Sources
      description: List the Sources registered in the TAMS service instance 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: reverse_order
          in: query
          description: Return Sources in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Sources by.
            `created` and `updated` sort most recent first by default.
            `label` sorts alphabetically by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - updated
              - label
        - name: tag.{name}
          in: query
          description: |
            Filter on Sources that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Sources that have a tag named {name} regardless of value.
            {name} MUST be URL encoded where special characters are present.
            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: 'schemas/content-format.json'
        - name: collected_by_ids
          in: query
          description: |
            Filter on Sources by the Source Collection(s) that collect them, given as a comma-separated list of Source IDs.
            Returns Sources whose `collected_by` includes at least one of the given Source IDs.
            An empty value (`collected_by_ids=`) returns only Sources that are not collected by any Source, i.e. top-level Sources with no `collected_by` value.
          schema:
            $ref: 'schemas/uuid-list-empty.json'
        - $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 service implementation
              schema:
                type: integer
            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:
              example:
                $ref: examples/sources-get-200.json
              schema:
                type: array
                items:
                  $ref: "schemas/source.json"
        "400":
          description: Bad request. Invalid query options.
  /sources/{sourceId}:
    parameters:
      - name: sourceId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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: schemas/source.json
              examples:
                basic:
                  summary: Source containing elemental video
                  externalValue: 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.
                  externalValue: examples/source-get-200-multi.json
                tags:
                  summary: Source with tags
                  description: Source example with tags set matching associated Flow
                  externalValue: examples/source-get-200-tags.json
        "404":
          description: The requested Source does not exist.
  /sources/{sourceId}/tags:
    parameters:
      - name: sourceId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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: "schemas/tags.json"
        "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} MUST be URL encoded where special characters are present.
      - name: sourceId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      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:
              oneOf:
                - type: string
                - type: array
                  items:
                    type: string
        required: true
      responses:
        "204":
          description: No content. The tag has been created or updated.
        "400":
          description: Bad request. Invalid Source tag value.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "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.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "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: 'schemas/uuid.json'
        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. This should be a human-readable description that may be showed in detailed views of Sources. The description should be longer and more detailed than `label`.
      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. This should be a human-readable description that may be showed in detailed views of Sources. The description should be longer and more detailed than `label`.
      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.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "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.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "404":
          description: The Source ID in the path is invalid.
  /sources/{sourceId}/label:
    parameters:
      - name: sourceId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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.
    get:
      summary: Source Label
      description: Returns the Source label property. This should be a very short, human-readable label that may be displayed in listings of Sources.
      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.
    put:
      summary: Create or Update Source Label
      description: Create or update the label property. This should be a very short, human-readable label that may be displayed in listings of Sources.
      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.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "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.
        "403":
          description: Forbidden. You do not have permission to modify this resource.
        "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: 'schemas/uuid.json'
        - name: timerange
          in: query
          description: Filter on Flows that overlap the given timerange.
          schema:
            default: _
            $ref: 'schemas/timerange.json'
        - name: format
          in: query
          description: Filter on Flow format.
          schema:
            $ref: 'schemas/content-format.json'
        - name: codec
          in: query
          description: Filter on Flow codec.
          schema:
            $ref: 'schemas/mime-type.json'
        - name: profile_id
          in: query
          description: Filter on Profile identifier.
          schema:
            $ref: 'schemas/uuid.json'
        - name: label
          in: query
          description: Filter on Flows that have the given label.
          schema:
            type: string
        - name: reverse_order
          in: query
          description: Return Flows in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Flows by.
            `created` and `metadata_updated` sort most recent first by default.
            `label` sorts alphabetically by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - metadata_updated
              - label
        - name: status
          in: query
          description: Filter on Flows on the value of `status`.
          schema:
            $ref: schemas/flow-status.json
        - name: tag.{name}
          in: query
          description: |
            Filter on flows that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Flows that have a tag named {name} regardless of value.
            {name} MUST be URL encoded where special characters are present.
            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
        - name: init_segments
          in: query
          description: Filter Flows on the value of `init_segments`.
          schema:
            type: boolean
        - name: collected_by_ids
          in: query
          description: |
            Filter on Flows by the Flow Collection(s) that collect them, given as a comma-separated list of Flow IDs.
            Returns Flows whose `collected_by` includes at least one of the given Flow IDs.
            An empty value (`collected_by_ids=`) returns only Flows that are not collected by any Flow, i.e. top-level Flows with no `collected_by` value.
          schema:
            $ref: 'schemas/uuid-list-empty.json'
        - $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 service implementation
              schema:
                type: integer
            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.
    get:
      summary: List Flows
      description: List the Flows registered in the TAMS service instance.
      operationId: GET_flows
      tags:
        - Flows
      parameters:
        - name: source_id
          in: query
          description: Filter on Source identifier.
          schema:
            $ref: 'schemas/uuid.json'
        - name: timerange
          in: query
          description: Filter on Flows that overlap the given timerange. An empty timerange returns Flows with no content.
          schema:
            default: _
            $ref: 'schemas/timerange.json'
        - name: format
          in: query
          description: Filter on Flow format.
          schema:
            $ref: 'schemas/content-format.json'
        - name: codec
          in: query
          description: Filter on Flow codec.
          schema:
            $ref: 'schemas/mime-type.json'
        - name: profile_id
          in: query
          description: Filter on Profile identifier.
          schema:
            $ref: 'schemas/uuid.json'
        - name: label
          in: query
          description: Filter on Flows that have the given label.
          schema:
            type: string
        - name: reverse_order
          in: query
          description: Return Flows in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Flows by.
            `created` and `metadata_updated` sort most recent first by default.
            `label` sorts alphabetically by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - metadata_updated
              - label
        - name: status
          in: query
          description: Filter on Flows on the value of `status`.
          schema:
            $ref: schemas/flow-status.json
        - name: tag.{name}
          in: query
          description: |
            Filter on flows that have a tag named {name} with a value in the given comma-seperated list of values.
            The {name} and the value MUST be URL encoded where special characters are present.
            Where the tag's value is a string, at least one of the given values will match.
            Where the tag's value is an array, at least one value in the array will match at least one of the given values.
            Partial string matches of the values are not valid.
          schema:
            $ref: 'schemas/url-tag-list.json'
        - name: tag_exists.{name}
          in: query
          description: |
            Filter on Flows that have a tag named {name} regardless of value.
            {name} MUST be URL encoded where special characters are present.
            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
        - name: init_segments
          in: query
          description: Filter Flows on the value of `init_segments`.
          schema:
            type: boolean
        - name: collected_by_ids
          in: query
          description: |
            Filter on Flows by the Flow Collection(s) that collect them, given as a comma-separated list of Flow IDs.
            Returns Flows whose `collected_by` includes at least one of the given Flow IDs.
            An empty value (`collected_by_ids=`) returns only Flows that are not collected by any Flow, i.e. top-level Flows with no `collected_by` value.
          schema:
            $ref: 'schemas/uuid-list-empty.json'
        - $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 service implementation
              schema:
                type: integer
            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:
              example:
                $ref: examples/flows-get-200.json
              schema:
                type: array
                items:
                  $ref: "schemas/flow-get.json"
        "400":
          description: Bad request. Invalid query options.
  /flows/{flowId}:
    parameters:
      - name: flowId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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 `timerange` in the response.
          schema:
            default: false
            type: boolean
        - name: timerange
          in: query
          description: Limit `timerange` of the response to the time range over which Segments partially or wholly overlap with the provided timerange.
          schema:
            default: _
            $ref: 'schemas/timerange.json'
      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 `timerange` in the response.
          schema:
            default: false
            type: boolean
        - name: timerange
          in: query
          description: Limit `timerange` of the response to the time range over which Segments partially or wholly overlap with the provided timerange.
          schema:
            default: _
            $ref: 'schemas/timerange.json'
      responses:
        "200":
          description: ""
          content:
            application/json:
              schema:
                $ref: schemas/flow-get.json
              examples:
                video:
                  summary: Video Flow - H.264 Codec
                  externalValue: examples/flow-get-200-video-h264.json
                rawvideo:
                  summary: Video Flow - Uncompressed (Quicktime)
                  externalValue: examples/flow-get-200-video-raw.json
                mxf_jpeg2k:
                  summary: Video Flow - JPEG-2000 (MXF container)
                  externalValue: examples/flow-get-200-video-jpeg-mxf.json
                mxf_h264:
                  summary: Video Flow - H.264 (MXF container)
                  externalValue: examples/flow-get-200-video-h264-mxf.json
                fmp4_h264:
                  summary: Video Flow - H.264 (fmp4 container)
                  externalValue: examples/flow-get-200-video-h264-fmp4.json
                jp2_jpeg2k_singleframe:
                  summary: Video Flow - JPEG-2000 (JP2 container, single frame segments)
                  externalValue: examples/flow-get-200-video-jpeg-jp2.json
                video_vfr:
                  summary: Video Flow - H.264 Codec, Variable Frame Rate
                  externalValue: examples/flow-get-200-video-h264-vfr.json
                video_cleanfeed:
                  summary: Video Flow - H.264 Codec, with Editorial Purpose Tag
                  externalValue: examples/flow-get-200-video-h264-cleanfeed.json
                audio:
                  summary: Audio Flow - AAC Codec
                  externalValue: examples/flow-get-200-audio-aac.json
                audio_wav:
                  summary: Audio Flow - PCM
                  externalValue: examples/flow-get-200-audio-wav.json
                jpegimage:
                  summary: Image Flow - JPEG Codec
                  externalValue: 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
                  externalValue: 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
                  externalValue: 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.
                  externalValue: 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
                  externalValue: 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.\n\nClients should aim to populate as many of the Flow metadata fields as possible and practical. The fewer parameters that are set, the higher the likelihood that reading clients will have to retrieve the media to determine technical metadata to e.g. configure decoders.\n\nSome parameters may be ignored/overridden by service implementations. This is to enable the Flow json-blob to be re-used with no/minimal editing in various use cases. Such parameters are called out in their description.\n\nService implementations SHOULD verify that Flow metadata is compatible with the associated Source.\nService implementations MAY accept modification/addition of parameters, and reflect such changes in the Source, where it will not bring any Flows of the Source into conflict.\nWhere metadata would result in any Flow of the Source coming into conflict, the request SHOULD be rejected with a 400 response.\nExamples of conflicting metadata include `format` not matching, or `role` or ordering in `source_collection` and `flow_collection` not matching.\nIt may also be possible for service implementations to detect some instances where multiple Flows should not be considered of the same Source, such as audio Flows with different numbers of tracks.\nFurther guidance on when Flows/Sources may be considered the same/different may be found in the [Practical Guidance for Media](https://specs.amwa.tv/ms-04/releases/v1.0.0/docs/3.0._Practical_Guidance_for_Media.html) section of AMWA MS-04.\n\nFlows can be created either by directly supplying all the required technical metadata or by referencing an existing Profile in the store.  \nWhen using a Profile, the Service Implementation will populate the Flow's technical parameters (format, codec, essence_parameters etc.) from that profile, along with the metadata provided.  \nIt is up to the Service Implementation whether this is normalised on the Flow creation or on read.\n\nWhen creating a flow using a Profile it is not possible to override any specific fields as this would invalidate the link to the Profile.  \nSupplying a Profile ID and any technical metadata should result in a 400 validation error.\n\nWhen updating a Flow created using a profile then  consideration needs to be given to the fields which were inherited. \nFor the standard fields (eg label, description, tags) which form part of the common Flow metadata and provided directly regardless of the Profile then these can be updated through the standard process.\n\nIn the scenario where the technical characteristics do need to be changed on a Flow created from a Profile then it is necessary to remove the link to the Profile as part of the update since it will no longer match the Profile entirely.\nThis is achieved by means of setting the `profile_id` field to an empty string as part of the update.\nThis will then break the link to the Profile and allow the store to update the technical parameters.\nIt should be noted that searching for Flows using a Profile will no longer include the updated Flow since it no longer matches or is linked to the Profile.\n"
      operationId: PUT_flows-flowId
      tags:
        - Flows
      requestBody:
        content:
          application/json:
            examples:
              audio:
                summary: Stereo audio Flow
                externalValue: examples/flow-put.json
              multi:
                summary: Multi-essence Flow
                externalValue: examples/flow-put-multi.json
              profile:
                summary: Flow created using a Profile
                externalValue: examples/flow-put-profile.json
            schema:
              $ref: schemas/flow-put.json
        required: true
      responses:
        "201":
          description: The Flow has been created.
          content:
            application/json:
              example:
                $ref: examples/flow-put-201.json
              schema:
                $ref: schemas/flow-get.json
        "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.

        Services SHALL only delete Objects when they are no longer referenced by any Flow Segments or other Objects (i.e. as init Objects).
      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: schemas/deletion-request.json
              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. Objects referenced in other Flows will not be deleted. Objects that are no longer referenced by any Segments 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: 'schemas/uuid.json'
        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: schemas/tags.json
        "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} MUST be URL encoded where special characters are present.
      - name: flowId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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:
                oneOf:
                  - type: string
                  - type: array
                    items:
                      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:
              oneOf:
                - type: string
                - type: array
                  items:
                    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: 'schemas/uuid.json'
        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. This should be a human-readable description that may be showed in detailed views of Flows. The description should be longer and more detailed than `label`.
      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. This should be a human-readable description that may be showed in detailed views of Flows. The description should be longer and more detailed than `label`.
      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: 'schemas/uuid.json'
        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.
    get:
      summary: Flow Label
      description: Returns the Flow label property. This should be a very short, human-readable label that may be displayed in listings of Flows.
      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.
    put:
      summary: Create or Update Flow Label
      description: Create or update the label property. This should be a very short, human-readable label that may be displayed in listings of Flows.
      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.
        "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}/read_only:
    parameters:
      - name: flowId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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. If set to 'true', service implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), and Flow Segments. Service implementations should also reject requests to the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage) endpoint for the Flow, and requests to delete the Flow.
      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. If set to 'true', service implementations SHOULD reject client requests to update Flow metadata (other than the read_only property), and Flow Segments. Service implementations should also reject requests to the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage) endpoint for the Flow, and requests to delete the Flow.
      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.
        "403":
          description: Forbidden. You do not have permission to modify this Flow.
        "404":
          description: The requested Flow does not exist.
  /flows/{flowId}/flow_collection:
    parameters:
      - name: flowId
        in: path
        required: true
        schema:
          $ref: 'schemas/uuid.json'
        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. An ordered list of Flows that are collected together by this Flow.
      operationId: GET_flows-flowId-flow-collection
      tags:
        - Flows
      responses:
        "200":
          description: ""
          content:
            application/json:
              example:
                $ref: examples/flow-collection-get-200.json
              schema:
                $ref: schemas/flow-collection.json
        "404":
          description: The requested Flow does not exist.
    put:
      summary: Create or Update Flow Collection
      description: |
        Create or update the Flow collection property. An ordered list of Flows that are collected together by this Flow.

        Service implementations SHOULD verify that Flow metadata is compatible with the associated Source.
        Service implementations MAY accept modification/addition of parameters, and reflect such changes in the Source, where it will not bring any Flows of the Source into conflict.
        Where metadata would result in any Flow of the Source coming into conflict, the request SHOULD be rejected with a 400 response.
      operationId: PUT_flows-flowId-flow-collection
      tags:
        - Flows
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/flow-collection-put.json
            schema:
              $ref: schemas/flow-collection.json
        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: 'schemas/uuid.json'
        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.

        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.
      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.

        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.
      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: 'schemas/uuid.json'
        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.

        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.
      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.

        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.

        When a Flow is created from a Profile then the average bit rate is inherited from the Profile.
        In this scenario is it not possible to update the average bit rate directly as it would invalidate the link to the Profile.
        Any attempt to update the average bitrate should be rejected by the store with a 400 error message as this is a bad request.
        To update the average bit rate then it is necessary to remove the link to the Profile first before updating directly.
      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: 'schemas/uuid.json'
        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 that partially or wholly overlap the timerange specified.
          schema:
            $ref: 'schemas/timerange.json'
        - 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` in the response.
            When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls` and `init_object.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` and `init_object.get_urls` to include in the response.
            Omitting `accept_get_urls` will result in no filtering of `get_urls` or `init_object.get_urls`.
            An empty `accept_get_urls` results in `get_urls` and `init_object.get_urls` being empty or omitted in the response.
            Flow Segment `get_urls` and `init_object.get_urls` with no label will only be returned if `accept_get_urls` is omitted.
            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` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/url-label-list.json'
        - name: accept_storage_ids
          in: query
          description: |
            A comma separated list of `storage_id`s of Flow Segment `get_urls` and `init_object.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` or `init_object.get_urls`.
            Flow Segment `get_urls` and `init_object.get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty.
            A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint.
            Where multiple filter query parameters are provided, the returned `get_urls` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/uuid-list.json'
        - 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` and `init_object.get_urls` in the response.
            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls` and `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            type: boolean
        - name: storage_backend_tag.{name}
          in: query
          description: |
            Filter Flow Segment `get_urls` and `init_object.get_urls` on tag values. This option is the same as the `tag.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: string
        - name: storage_backend_tag_exists.{name}
          in: query
          description: |
            Filter Flow Segment `get_urls` and `init_object.get_urls` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: boolean
        - name: include_object_timerange
          in: query
          description: |
            If set to `true`, the underlying object's timerange should appear in the response.
            Assume `false` if omitted.
          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 service implementation
              schema:
                type: integer
            X-Paging-Timerange:
              description: Identifies the timerange for the returned data set.
              schema:
                $ref: 'schemas/timerange.json'
            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 Storage Backend type, which is indicated in the [/service/storage-backends](#/operations/GET_storage-backends) resource, determines the information that is included in the response to allow the Flow Segment's Media Object to be downloaded by the client.
        The examples provided here are for the "http_object_store" Storage Backend type which MUST include a `get_urls` property that contains the HTTP URLs for downloading the Media Object - service implementations should generate this internally.

        The Flow Segment may include timing adjustment information that the client needs to apply when extracting the samples from the Media Object.
        The timestamp of a sample on the Flow Segment's timeline (`segment_ts`) is the timestamp of that sample embedded in or derived from the internal timing of the Media Object (`media_object_ts`) adjusted by `ts_offset`: `segment_ts = media_object_ts + ts_offset`.

        It may also use a subset of the samples in the Media Object, and if the `include_object_timerange=true` parameter is set, the object's timerange will also be returned to aid identifying which samples to skip.

        Segments are sorted by timerange, in ascending order by default.
        As Segments in TAMS do not overlap, either of the start or end timestamp of the timerange may be used as the sort key.
        Service implementations MUST take clusivity markers of the timerange into account.
        Service implementations should consider edge cases such as a timerange with an exclusive end `[1:0_2:0)` followed by an instantaneous timerange of `[2:0]`.

        Clients should use the pagination options to limit the results to a timerange and/or count.
        Service implementations may also limit the results returned.
        This will be signalled via the paging headers in the response.
        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.

        Where Flow Segments reference initialisation segment Objects with the same ID, the initialisation segment is the same.
        Consuming clients may choose to ignore initialisation segment Objects that haven't changed in subsequent Flow Segments.

        When making requests to provided `get_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials.
      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 that partially or wholly overlap the timerange specified.
          schema:
            $ref: 'schemas/timerange.json'
        - 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` in the response.
            When `verbose_storage` is `false` only `url`, `presigned`, and `label` will be included in `get_urls` and `init_object.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` and `init_object.get_urls` to include in the response.
            Omitting `accept_get_urls` will result in no filtering of `get_urls` or `init_object.get_urls`.
            An empty `accept_get_urls` results in `get_urls` and `init_object.get_urls` being empty or omitted in the response.
            Flow Segment `get_urls` and `init_object.get_urls` with no label will only be returned if `accept_get_urls` is omitted.
            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` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/url-label-list.json'
        - name: accept_storage_ids
          in: query
          description: |
            A comma separated list of `storage_id`s of Flow Segment `get_urls` and `init_object.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` or `init_object.get_urls`.
            Flow Segment `get_urls` and `init_object.get_urls` with no storage ID will only be returned if `accept_storage_ids` is omitted or empty.
            A full list of available `storage_id`s may be found at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint.
            Where multiple filter query parameters are provided, the returned `get_urls` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/uuid-list.json'
        - 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` and `init_object.get_urls`.
            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls` and `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            type: boolean
        - name: storage_backend_tag.{name}
          in: query
          description: |
            Filter Flow Segment `get_urls` and `init_object.get_urls` on tag values. This option is the same as the `tag.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: string
        - name: storage_backend_tag_exists.{name}
          in: query
          description: |
            Filter Flow Segment `get_urls` and `init_object.get_urls` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: boolean
        - name: include_object_timerange
          in: query
          description: |
            If set to `true`, the underlying object's timerange should appear in the response.
            Assume `false` if omitted.
          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 service implementation
              schema:
                type: integer
            X-Paging-Timerange:
              description: Identifies the timerange for the returned data set.
              schema:
                $ref: 'schemas/timerange.json'
            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: schemas/flow-segment.json
              examples:
                basic:
                  summary: Basic Example
                  externalValue: examples/flow-segments-get-200.json
                sample_count:
                  summary: Partial Segment
                  description: |
                    This example shows re-use of existing Media Objects
                  externalValue: examples/flow-segments-get-200-object-timerange.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 service has expressed a preference for the "pipeline-a" URLs by putting them first in the list.
                  externalValue: examples/flow-segments-get-200-multiple-urls.json
                init_segments:
                  summary: Objects with initialisation segments
                  description: |
                    This example shows how Media Objects signal the use of initialisation segments.
                    Note the re-use of the same initialisation segment in some consecutive Flow Segments.
                  externalValue: examples/flow-segments-get-200-init.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.

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

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

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

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

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

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

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

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

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

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

        If an Object has previously been registered as an initialisation segment (i.e. via `init_object_id`), Service implementations SHOULD reject its use as a media segment (i.e. via `object_id`).
        If an Object has previously been registered as a media segment (i.e. via `object_id`), Service implementations SHOULD reject its use as an initialisation segment (i.e. via `init_object_id`).
      operationId: POST_flows-flowId-segments
      tags:
        - FlowSegments
      requestBody:
        content:
          application/json:
            example:
              $ref: examples/flow-segment-post.json
            schema:
              oneOf:
                - $ref: schemas/flow-segment-post.json
                - type: array
                  items:
                    $ref: schemas/flow-segment-post.json
        required: true
      responses:
        "200":
          description: Partial success creating Segments returning list of failed Segments.
          content:
            application/json:
              schema:
                $ref: schemas/flow-segment-bulk-failure.json
              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.

        Services SHALL only delete Objects when they are no longer referenced by any Flow Segments or other Objects (i.e. as init Objects).
      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: 'schemas/timerange.json'
        - 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: schemas/deletion-request.json
              example:
                $ref: examples/deletion-request-get-200.json
        "204":
          description: No content. The Flow Segments have been or will be deleted. Objects referenced in other Segments will not be deleted. Objects that are no longer referenced by any Segments 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: 'schemas/uuid.json'
        description: The Flow identifier.
    post:
      summary: Allocate Initial Flow Storage
      description: |
        Allocate initial storage locations for writing Objects.

        The Storage Backend type, which is indicated in the [/service](#/operations/GET_service) resource, determines the information provided in the response.
        The examples and description below are for the "http_object_store" Storage Backend type.
        This Storage Backend type provides HTTP URLs for uploading and downloading Objects in buckets.

        The response will include a PUT URL that a client uses to upload the Object.
        The client is expected to register the Flow Segment using the [/flows/{flowId}/segments](#/operations/POST_flows-flowId-segments) endpoint once the upload is complete.

        Clients MAY request Objects in batches to reduce the number of HTTP requests made to the Service.
        Clients are not expected to use all of the Objects they requested.
        Objects will likely go unused in cases such as shutdown of ingesting clients, the end of ingested live streams, and unexpected network congestion.
        Clients SHOULD, however, adapt the number of Objects they request such that they may reasonably expect to use them before the timeout advertised in [`min_object_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema).

        Where media format make use of initialisation segments, the mime-type of those initialisation segments may differ from that of the media segments.
        In such cases, the `container` on the Flow will be set to the mime-type of the media segments and is the assumed default.
        A separate request to this endpoint should be made to allocate storage for the initialisation segment(s) with `content-type` set to the mime type of the initialisation segment(s).
        `content-type` MUST NOT be set in the request body of this end point at any other time.
        Initialisation segment Objects SHOULD be re-used wherever possible.

        Service implementations need to handle situations where Objects are not used, and where content is were uploaded but the Object is not successfully registered against a Flow Segment or as an init Object against Media Objects.
        In these circumstances, Services should garbage collect Objects after the timeout advertised in [`min_object_timeout` at the `/service`](#/operations/GET_service) endpoint.

        When making requests to provided `put_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials.
      operationId: POST_flows-flowId-storage
      tags:
        - MediaStorage
      requestBody:
        content:
          application/json:
            examples:
              limit:
                summary: limit
                externalValue: examples/flow-storage-post.json
              object_ids:
                summary: object_ids
                externalValue: examples/flow-storage-post-object_ids.json
            schema:
              $ref: schemas/flow-storage-post.json
      responses:
        "201":
          description: Storage locations for writing Objects.
          content:
            application/json:
              schema:
                $ref: schemas/flow-storage.json
              examples:
                mpegts:
                  summary: MPEG-TS container Flow
                  description: Flow using MPEG-TS as the container format, writing to a cloud object store
                  externalValue: examples/flow-storage-post-201.json
                wav_proxy:
                  summary: WAV Flow
                  description: Flow using WAV as the container format, writing to an HTTP interface running on the same origin as the TAMS API
                  externalValue: examples/flow-storage-post-201-wav.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: Object Information
      description: Return Flow references and other information about init or Media Objects.
      operationId: HEAD_objects
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          description: The Object identifier. The Object ID may include special characters such as `/` which should be URL encoded.
          required: true
          schema:
            type: string
        - 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` and `init_object.get_urls`.
          schema:
            default: false
            type: boolean
        - name: accept_get_urls
          in: query
          description: |
            A comma separated list of labels of Object `get_urls` and `init_object.get_urls` to include in the response.
            Omitting `accept_get_urls` will result in no filtering of `get_urls` or `init_object.get_urls`.
            An empty `accept_get_urls` results in `get_urls` and `init_object.get_urls` being empty or omitted in the response.
            Object `get_urls` and `init_object.get_urls` with no label will only be returned if `accept_get_urls` is omitted.
            Without `get_urls` or `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/url-label-list.json'
        - name: accept_storage_ids
          in: query
          description: |
            A comma separated list of `storage_id`s of Object `get_urls` and `init_object.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` or `init_object.get_urls`.
            Object `get_urls` and `init_object.get_urls` with no storage ID will only be returned if `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` and `init_object.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` and `init_object.get_urls`.
            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls` and `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            type: boolean
        - name: flow_tag.{name}
          in: query
          description: |
            Filter `referenced_by_flows` on tag values. This option is the same as the `tag.{name}` query parameter on the `/flows/` API endpoint.
          schema:
            type: string
        - name: flow_tag_exists.{name}
          in: query
          description: |
            Filter `referenced_by_flows` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/flows/` API endpoint.
          schema:
            type: boolean
        - name: storage_backend_tag.{name}
          in: query
          description: |
            Filter `get_urls` and `init_object.get_urls` on tag values. This option is the same as the `tag.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: string
        - name: storage_backend_tag_exists.{name}
          in: query
          description: |
            Filter `get_urls` and `init_object.get_urls` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/service/storage-backends` API endpoint.
          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' 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 service 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 Object does not exist. 404 MUST be returned if the ID has been assigned via the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage), but not yet registered against a Flow Segment.
    get:
      summary: Object Information
      description: |
        Contains Flows that references the init/Media Object and other information.

        The paging query parameters and headers are required for the list of Flow references in the Object.
        Service 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 Object is used in many Flows.

        When making requests to provided `get_url`s that are not presigned, clients SHOULD include credentials if the provided URL is on the same origin as the Service itself, akin to the `same-origin` mode in the [WhatWG Fetch Standard](https://fetch.spec.whatwg.org/#concept-request-credentials-mode). Services MAY support the use of out-of-band credentials where the provided URL is on a different origin to the Service itself. Services SHOULD NOT solely require the use of out-of-band credentials.
      operationId: GET_objects
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          description: The Object identifier. The Object ID may include special characters such as `/` which should be URL encoded.
          required: true
          schema:
            type: string
        - 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` and `init_object.get_urls`.
          schema:
            default: false
            type: boolean
        - name: accept_get_urls
          in: query
          description: |
            A comma separated list of labels of Object `get_urls` and `init_object.get_urls` to include in the response.
            Omitting `accept_get_urls` will result in no filtering of `get_urls` or `init_object.get_urls`.
            An empty `accept_get_urls` results in `get_urls` and `init_object.get_urls` being empty or omitted in the response.
            Object `get_urls` and `init_object.get_urls` with no label will only be returned if `accept_get_urls` is omitted.
            Without `get_urls` and `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            $ref: 'schemas/url-label-list.json'
        - name: accept_storage_ids
          in: query
          description: |
            A comma separated list of `storage_id`s of Object `get_urls` and `init_object.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` or `init_object.get_urls`.
            Object `get_urls` and `init_object.get_urls` with no storage ID will only be returned if `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` and `init_object.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` and `init_object.get_urls`.
            If set to `false`, only non-presigned URLs (i.e. those whos `presigned` property is `false`) will be returned in `get_urls` and `init_object.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` and `init_object.get_urls` will match all filters.
          schema:
            type: boolean
        - name: flow_tag.{name}
          in: query
          description: |
            Filter `referenced_by_flows` on tag values. This option is the same as the `tag.{name}` query parameter on the `/flows/` API endpoint.
          schema:
            type: string
        - name: flow_tag_exists.{name}
          in: query
          description: |
            Filter `referenced_by_flows` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/flows/` API endpoint.
          schema:
            type: boolean
        - name: storage_backend_tag.{name}
          in: query
          description: |
            Filter `get_urls` and `init_object.get_urls` on tag values. This option is the same as the `tag.{name}` query parameter on the `/service/storage-backends` API endpoint.
          schema:
            type: string
        - name: storage_backend_tag_exists.{name}
          in: query
          description: |
            Filter `get_urls` and `init_object.get_urls` on tag names. This option is the same as the `tag_exists.{name}` query parameter on the `/service/storage-backends` API endpoint.
          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' 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 service 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:
              examples:
                basic:
                  summary: Basic example
                  externalValue: examples/objects-get-200.json
                init_segment:
                  summary: Object that makes use of an initialisation segment
                  externalValue: examples/objects-get-200-init.json
              schema:
                $ref: "schemas/object.json"
        "400":
          description: Bad request. Invalid query options.
        "404":
          description: The requested Object does not exist. 404 MUST be returned if the ID has been assigned via the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage), but not yet registered against a Flow Segment.
  /objects/{objectId}/instances:
    post:
      summary: Register an Object instance
      description: |
        Request the service to create an Object instance on a new Storage Backend. Or add a new uncontrolled URL to `get_urls`.

        To request the duplication of the Object to a new Storage Backend, clients POST a `storage_id` to this endpoint that does not currently have an instance of the Object. The API will then:

        - Allocate storage for Object `objectId` on Storage Backend `storage_id`
        - Copy the Object from an existing location to the newly allocated storage
        - Start advertising the new copy in `get_urls` once ready

        The API instances SHOULD be capable of handling the case where the only existant instances are uncontrolled.

        API instances SHALL NOT cascade the creation of new Object instances to initialisation Objects.
        Clients MUST initiate the creation of new Object instances of initialisation Objects directly.

        Where a client has written a new uncontrolled Object instance, the client is responsible for ensuring that the Object written is complete and correct before registering it with this method.

        All instances of an Object MUST be identical.
      operationId: POST_objects-instances
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          description: The Object identifier. The Object ID may include special characters such as `/` which should be URL encoded.
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            examples:
              controlled:
                summary: Registering a controlled instance
                externalValue: examples/objects-instances-controlled-post.json
              uncontrolled:
                summary: Registering a uncontrolled instance
                externalValue: examples/objects-instances-uncontrolled-post.json
            schema:
              $ref: schemas/objects-instances-post.json
        required: true
      responses:
        "201":
          description: Object instance successfully registered.
        "400":
          description: Bad request. Invalid request JSON.
        "403":
          description: Forbidden. You do not have permission to modify this Object.
        "404":
          description: The Object does not exist. 404 MUST be returned if the ID has been assigned via the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage), but not yet registered against a Flow Segment.
    delete:
      summary: Delete an Object instance
      description: |
        Delete an instance of a Object.

        One of `storage_id` or `label` MUST be specified in the query parameters. `storage_id` SHOULD be used where `controlled` is `True` for the instance.

        API instances should remove the Object instance from the `get_urls` list and then, if the instance is controlled, delete the Object instance from storage.

        API instances SHOULD prevent clients from deleting all Object instances. Additionally, API instances MAY prevent clients from deleting all controlled Object instances. Where clients wish to remove all copies of an Object from the store, they should do so by deleting all Flows or Flow Segments which reference the Object.

        API instances SHALL NOT cascade the deletion of Object instances to initialisation Objects.
        Clients MUST initiate the deletion of Object instances of initialisation Objects directly.
      operationId: DELETE_objects-instances
      tags:
        - Objects
      parameters:
        - name: objectId
          in: path
          description: The Object identifier. The Object ID may include special characters such as `/` which should be URL encoded.
          required: true
          schema:
            type: string
        - name: storage_id
          in: query
          description: The storage_id identifying the Object instance to be deleted.
          schema:
            type: string
        - name: label
          in: query
          description: The label identifying the Object instance to be deleted.
          schema:
            type: string
      responses:
        "204":
          description: No content. The Object instance has been deleted.
        "400":
          description: Bad request. Invalid query options.
        "403":
          description: Forbidden. You do not have permission to modify this Object.
        "404":
          description: The requested Object ID in the path is invalid. 404 MUST be returned if the ID has been assigned via the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage), but not yet registered against a Flow Segment.
  /flow-delete-requests:
    head:
      summary: List Flow Delete Requests
      description: Return flow-delete-requests path headers
      operationId: HEAD_flow-delete-requests
      tags:
        - FlowDeleteRequests
      parameters:
        - name: reverse_order
          in: query
          description: Return Flow Delete Requests in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Flow Delete Requests by.
            `created` and `expiry` sort most recent first by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - expiry
        - $ref: '#/components/parameters/trait_resource_paged_key'
        - $ref: '#/components/parameters/trait_paged_limit'
      responses:
        "200":
          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 service implementation
              schema:
                type: integer
            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
          $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
      parameters:
        - name: reverse_order
          in: query
          description: Return Flow Delete Requests in reverse order.
          schema:
            default: false
            type: boolean
        - name: sort_by
          in: query
          description: |
            Parameter to sort Flow Delete Requests by.
            `created` and `expiry` sort most recent first by default.
            Sorting may be reversed using the `reverse_order` query parameter.
            Assume `created` if not set.
            For resources where the selected parameter is unset, `id` shall be used.
            Resources using this fallback shall be sorted after those that aren't by default, and before when `reverse_order` is `true`.
          schema:
            type: string
            enum:
              - created
              - expiry
        - $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 service implementation
              schema:
                type: integer
            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: schemas/deletion-request.json
              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 Flow Segments that are being deleted.

        A deletion request is created when a client DELETEs a long timerange 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: schemas/deletion-request.json
              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 service 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: "schemas/flow-get.json"
  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: "schemas/flow-get.json"
  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: "schemas/uuid.json"
      responses:
        "200":
          description: Webhook received successfully
  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: "schemas/uuid.json"
                    segments:
                      type: array
                      items:
                        $ref: 'schemas/flow-segment.json'
      responses:
        "200":
          description: Webhook received successfully
  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_deleted
                event:
                  type: object
                  required:
                    - flow_id
                    - timerange
                  properties:
                    flow_id:
                      $ref: "schemas/uuid.json"
                    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: 'schemas/timerange.json'
      responses:
        "200":
          description: Webhook received successfully
  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 service 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: "schemas/source.json"
      responses:
        "200":
          description: Webhook received successfully
  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: "schemas/source.json"
      responses:
        "200":
          description: Webhook received successfully
  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: "schemas/uuid.json"
      responses:
        "200":
          description: Webhook received successfully
components:
  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. Service 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. Service 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 TAMS service instance including the token.

        Clients should retain the token in the `access_token` query string parameter, and use it for subsequent requests to the TAMS service instance 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.
  - name: Profiles
    description: Centralised management of the technical characteristics of a flow
    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
  - name: Objects
    description: The Object in the Storage Backend(s) that contains the media essence.
  - name: MediaStorage
    description: The system that stores the 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