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: '#/components/schemas/service' example: $ref: examples/service-get-200.json post: summary: Update Service Information description: Update the service info. operationId: POST_service tags: - Service requestBody: content: application/json: example: $ref: examples/service-post.json schema: $ref: '#/components/schemas/servicepost' required: true responses: '200': description: Success. The service info has been updated. '400': description: Bad request. Invalid service JSON. '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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/storagebackendslist' 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: '#/components/schemas/mimetype' - 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: '#/components/schemas/contentformat' - name: codec in: query description: Filter on Profile codec. schema: $ref: '#/components/schemas/mimetype' - 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: '#/components/schemas/profile' '400': description: Bad request. Invalid query options. /service/profiles/{profileId}: parameters: - name: profileId in: path required: true schema: $ref: '#/components/schemas/uuid' 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: '#/components/schemas/profile' 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: '#/components/schemas/profile' required: true responses: '201': description: The Profile has been created. content: application/json: example: $ref: examples/profile-post-201.json schema: $ref: '#/components/schemas/profile' '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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/webhookget' '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: '#/components/schemas/webhookpost' required: true responses: '201': description: Success. The webhook has been registered. content: application/json: example: $ref: examples/webhook-get-200.json schema: $ref: '#/components/schemas/webhookget' '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: '#/components/schemas/uuid' 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: '#/components/schemas/webhookget' '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: '#/components/schemas/webhookput' required: true responses: '201': description: Success. The webhook has been updated content: application/json: example: $ref: examples/webhook-get-200.json schema: $ref: '#/components/schemas/webhookget' '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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/contentformat' - 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: '#/components/schemas/uuidlistempty' - $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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/contentformat' - 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: '#/components/schemas/uuidlistempty' - $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: '#/components/schemas/source' '400': description: Bad request. Invalid query options. /sources/{sourceId}: parameters: - name: sourceId in: path required: true schema: $ref: '#/components/schemas/uuid' description: The Source identifier. head: summary: Source Details description: Return Source headers operationId: HEAD_sources-sourceId tags: - Sources responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Source Details description: Returns Source metadata. operationId: GET_sources-sourceId tags: - Sources responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/source' examples: basic: summary: Source containing elemental video 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: '#/components/schemas/uuid' description: The Source identifier. head: summary: List Source Tags description: Return Source tags path headers operationId: HEAD_sources-sourceId-tags tags: - Sources responses: '200': $ref: '#/components/responses/trait_resource_listing_head_200' '404': description: The requested Source does not exist. get: summary: List Source Tags description: Returns the Source tags. operationId: GET_sources-sourceId-tags tags: - Sources responses: '200': description: '' content: application/json: example: ingested_by: ingest_service_api schema: $ref: '#/components/schemas/tags' '404': description: The requested Source does not exist. /sources/{sourceId}/tags/{name}: parameters: - name: name in: path required: true schema: type: string description: The tag name. {name} MUST be URL encoded where special characters are present. - name: sourceId in: path required: true schema: $ref: '#/components/schemas/uuid' description: The Source identifier. head: summary: Source Tag Value description: Return Source tag path headers operationId: HEAD_sources-sourceId-tags-name tags: - Sources responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': description: The requested Source or tag does not exist. get: summary: Source Tag Value description: Return the tag value associated with the tag name. operationId: GET_sources-sourceId-tags-name tags: - Sources responses: '200': description: '' content: application/json: example: | "ingest_service_api" schema: 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: '#/components/schemas/uuid' description: The Source identifier. head: summary: Source Description description: Return Source description path headers operationId: HEAD_sources-sourceId-description tags: - Sources responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Source Description description: Returns the Source description property. 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: '#/components/schemas/uuid' description: The Source identifier. head: summary: Source Label description: Return Source label path headers operationId: HEAD_sources-sourceId-label tags: - Sources responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': description: The requested Source does not exist. 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: '#/components/schemas/uuid' - name: timerange in: query description: Filter on Flows that overlap the given timerange. schema: default: _ $ref: '#/components/schemas/timerange' - name: format in: query description: Filter on Flow format. schema: $ref: '#/components/schemas/contentformat' - name: codec in: query description: Filter on Flow codec. schema: $ref: '#/components/schemas/mimetype' - name: profile_id in: query description: Filter on Profile identifier. schema: $ref: '#/components/schemas/uuid' - 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: '#/components/schemas/flowstatus' - 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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/uuidlistempty' - $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: '#/components/schemas/uuid' - name: timerange in: query description: Filter on Flows that overlap the given timerange. An empty timerange returns Flows with no content. schema: default: _ $ref: '#/components/schemas/timerange' - name: format in: query description: Filter on Flow format. schema: $ref: '#/components/schemas/contentformat' - name: codec in: query description: Filter on Flow codec. schema: $ref: '#/components/schemas/mimetype' - name: profile_id in: query description: Filter on Profile identifier. schema: $ref: '#/components/schemas/uuid' - 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: '#/components/schemas/flowstatus' - 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: '#/components/schemas/urltaglist' - 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: '#/components/schemas/uuidlistempty' - $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: '#/components/schemas/flowget' '400': description: Bad request. Invalid query options. /flows/{flowId}: parameters: - name: flowId in: path required: true schema: $ref: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Details description: Return Flow path headers operationId: HEAD_flows-flowId tags: - Flows parameters: - name: include_timerange in: query description: Include `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: '#/components/schemas/timerange' responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '400': description: Bad request. Invalid query options. '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Details description: Returns Flow metadata. operationId: GET_flows-flowId tags: - Flows parameters: - name: include_timerange in: query description: Include `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: '#/components/schemas/timerange' responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/flowget' 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: '#/components/schemas/flowput' required: true responses: '201': description: The Flow has been created. content: application/json: example: $ref: examples/flow-put-201.json schema: $ref: '#/components/schemas/flowget' '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: '#/components/schemas/deletionrequest' example: $ref: examples/deletion-request-get-200.json '204': description: No content. The Flow has been deleted and the Flow Segments have been or will be deleted. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: List Flow Tags description: Return Flow tags path headers operationId: HEAD_flows-flowId-tags tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_listing_head_200' '404': description: The requested Flow does not exist. get: summary: List Flow Tags description: Returns the Flow tags. operationId: GET_flows-flowId-tags tags: - Flows responses: '200': description: '' content: application/json: example: $ref: examples/flow-tags-get-200.json schema: $ref: '#/components/schemas/tags' '404': description: The requested Flow does not exist. /flows/{flowId}/tags/{name}: parameters: - name: name in: path required: true schema: type: string description: The tag name. {name} MUST be URL encoded where special characters are present. - name: flowId in: path required: true schema: $ref: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Tag Value description: Return Flow tag path headers operationId: HEAD_flows-flowId-tags-name tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': description: The requested Flow or tag does not exist. get: summary: Flow Tag Value description: Return the tag value associated with the tag name. operationId: GET_flows-flowId-tags-name tags: - Flows responses: '200': description: '' content: application/json: example: | "full" schema: 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Description description: Return Flow description path headers operationId: HEAD_flows-flowId-description tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Description description: Returns the Flow description property. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Label description: Return Flow label path headers operationId: HEAD_flows-flowId-label tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': description: The requested Flow does not exist. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Read-Only description: Return Flow read_only path headers operationId: HEAD_flows-flowId-read-only tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Read-Only description: Returns the Flow read_only property. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Collection description: Returns the Flow collection path headers operationId: HEAD_flows-flowId-flow-collection tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Collection description: Returns the Flow collection property. 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: '#/components/schemas/flowcollection' '404': description: The requested Flow does not exist. put: summary: Create or Update Flow Collection description: | Create or update the Flow collection property. 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: '#/components/schemas/flowcollection' required: true responses: '204': description: No content. The Flow collection has been created or updated. '400': description: Bad request. Invalid Flow collection. '403': description: Forbidden. You do not have permission to modify this Flow. It may be marked read-only. '404': description: The requested Flow does not exist. delete: summary: Delete Flow Collection description: Delete the Flow collection property. operationId: DELETE_flows-flowId-flow-collection tags: - Flows responses: '204': description: No content. The Flow collection property has been deleted. '403': description: Forbidden. You do not have permission to modify this Flow. It may be marked read-only. '404': description: The requested Flow ID in the path is invalid. /flows/{flowId}/max_bit_rate: parameters: - name: flowId in: path required: true schema: $ref: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Maximum Bit Rate description: Returns the Flow max bit rate path headers operationId: HEAD_flows-flowId-max-bit-rate tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Maximum Bit Rate description: | Returns the Flow max bit rate property. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: Flow Average Bit Rate description: Returns the Flow average bit rate path headers operationId: HEAD_flows-flowId-avg-bit-rate tags: - Flows responses: '200': $ref: '#/components/responses/trait_resource_info_head_200' '404': $ref: '#/components/responses/trait_resource_info_head_404' get: summary: Flow Average Bit Rate description: | Returns the Flow average bit rate property. 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: '#/components/schemas/uuid' description: The Flow identifier. head: summary: List Flow Segments description: Return Flow Segments path headers operationId: HEAD_flows-flowId-segments tags: - FlowSegments parameters: - name: object_id in: query description: Filter on Object identifier. schema: type: string - name: timerange in: query description: Return only the results that partially or wholly overlap the timerange specified. schema: $ref: '#/components/schemas/timerange' - name: reverse_order in: query description: Return Segments in reverse time order. schema: default: false type: boolean - name: verbose_storage in: query description: | Include storage metadata in `get_urls` 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: '#/components/schemas/urllabellist' - 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: '#/components/schemas/uuidlist' - 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: '#/components/schemas/timerange' X-Paging-Count: description: The number of items in the returned data set. schema: type: integer X-Paging-Reverse-Order: description: The items are returned in reverse order. schema: type: boolean X-Paging-NextKey: description: Opaque string that can be supplied to the `page` query parameter to get the next page of results. schema: type: string content: application/json: schema: type: string '400': description: Bad request. Invalid query options. '404': description: The Flow ID in the path is invalid. get: summary: List Flow Segments description: | Returns the Flow Segments. The Flow Segment provides information about the Media Object. The 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: '#/components/schemas/timerange' - name: reverse_order in: query description: Return Segments in reverse time order. schema: default: false type: boolean - name: verbose_storage in: query description: | Include storage metadata in `get_urls` 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: '#/components/schemas/urllabellist' - 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: '#/components/schemas/uuidlist' - 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: '#/components/schemas/timerange' X-Paging-Count: description: The number of items in the returned data set. schema: type: integer X-Paging-Reverse-Order: description: The items are returned in reverse order. schema: type: boolean X-Paging-NextKey: description: Opaque string that can be supplied to the `page` query parameter to get the next page of results. schema: type: string content: application/json: schema: type: array items: $ref: '#/components/schemas/flowsegment' examples: basic: summary: Basic Example 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: '#/components/schemas/flowsegmentpost' - type: array items: $ref: '#/components/schemas/flowsegmentpost' required: true responses: '200': description: Partial success creating Segments returning list of failed Segments. content: application/json: schema: $ref: '#/components/schemas/flowsegmentbulkfailure' example: $ref: examples/flow-segment-partial-failure.json '201': description: created. The flow Segment or list of Segments has been created. '400': description: Bad request. Invalid Flow Segment JSON or the Flow 'container' is not set. '403': description: Forbidden. You do not have permission to modify this Flow. It may be marked read-only. '404': description: The Flow does not exist. delete: summary: Delete Flow Segment description: | Deletes the Flow Segments. If the deletion takes too long then this request will return 202 Accepted and the `Location` header will point to a Flow Delete Request to monitor deletion progress. 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: '#/components/schemas/timerange' - name: object_id in: query description: Filter on Object identifier. schema: type: string responses: '202': description: This request has taken longer than the configured timeout, and will continue asynchronously headers: Location: schema: type: string example: /flow-delete-request/{request-id} content: application/json: schema: $ref: '#/components/schemas/deletionrequest' example: $ref: examples/deletion-request-get-200.json '204': description: No content. The Flow Segments have been or will be deleted. 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: '#/components/schemas/uuid' 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: '#/components/schemas/flowstoragepost' responses: '201': description: Storage locations for writing Objects. content: application/json: schema: $ref: '#/components/schemas/flowstorage' 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: '#/components/schemas/urllabellist' - 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: '#/components/schemas/urllabellist' - 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: '#/components/schemas/object' '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: '#/components/schemas/objectsinstancespost' 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: '#/components/schemas/deletionrequest' 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: '#/components/schemas/deletionrequest' example: $ref: examples/deletion-request-get-200.json '404': description: The requested Flow delete request does not exist. webhooks: flows/created: post: security: - {} requestBody: content: application/json: schema: title: Flow Created Notification description: Information about a Flow which has been newly created in this 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: '#/components/schemas/flowget' flows/updated: post: security: - {} requestBody: content: application/json: schema: title: Flow Updated Notification description: Information about a Flow for which the metadata has been modified. required: - event_timestamp - event_type - event properties: event_timestamp: description: Timestamp at which the Flow was modified type: string format: date-time event_type: type: string const: flows/updated event: type: object required: - flow properties: flow: $ref: '#/components/schemas/flowget' flows/deleted: post: security: - {} requestBody: content: application/json: schema: title: Flow Deleted Notification description: Notification that a Flow has been deleted (or scheduled for deletion). required: - event_timestamp - event_type - event properties: event_timestamp: description: Timestamp at which the Flow was modified type: string format: date-time event_type: type: string const: flows/deleted event: type: object required: - flow_id properties: flow_id: $ref: '#/components/schemas/uuid' 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: '#/components/schemas/uuid' segments: type: array items: $ref: '#/components/schemas/flowsegment' 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: '#/components/schemas/uuid' timerange: description: The timerange of Segments that have been deleted. The timerange MUST intersect with a Segment which has been deleted at both start and end (e.g. it cannot start or end in empty space). $ref: '#/components/schemas/timerange' 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: '#/components/schemas/source' 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: '#/components/schemas/source' 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: '#/components/schemas/uuid' 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. schemas: collectionitem: title: Collection Item description: Describes how an entity (Source or Flow) is collected into another entity of the same type type: object required: - id properties: id: description: Source or Flow Identifier of the member of this collection. Sources MUST only collect Sources, and Flows MUST only collect Flows. Must already be registered in this service instance $ref: '#/components/schemas/uuid' role: description: The purpose of this element in the collection, primarily intended to be human-readable. type: string containermapping: title: Container Mapping description: Defines the location of Flow essence data in a container track type: object properties: track_index: description: A zero-based and sequential track index in the container. This assumes a reliable ordering of tracks type: integer minimum: 0 format_track_index: description: A zero-based and sequential track index in the container for a particular Flow format. A container with a video and 2 audio tracks would have a format_track_index 0 for the video Flow and format_track_index 0 and 1 for the audio Flows. This assumes a reliable ordering of tracks for each Flow format type: integer minimum: 0 audio_track: description: Mapping for channels in audio tracks to the Flow channels type: object properties: channel_numbers: description: Array of (zero-based) container channel numbers in Flow order type: array minItems: 1 items: type: integer minimum: 0 channel_range: description: Inclusive range of (zero-based) container channel numbers type: string pattern: ^[0-9]+_[0-9]+$ mp2ts_container: description: Mapping to MPEG-2 Transport Stream containers, ISO/IEC 13818-1 or ITU-T Recommendation H.222.0 type: object properties: pid: description: The packet ID for the elementary stream packets type: integer mxf_container: description: Mapping to Material Exchange Format containers, SMPTE ST 377-1 type: object properties: package_uid: description: The package UID. Either a SMPTE UMID URN or UUID URN type: string pattern: ^urn:smpte:umid:[0-9a-fA-F]{8}(.[0-9a-fA-F]{8}){7}$|^urn:uuid:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ track_id: description: The track ID in the package type: integer isobmff_container: description: Mapping to ISO Base Media File Format (e.g. MP4 and MOV) containers, ISO/IEC 14496-12 type: object properties: track_id: description: The track ID type: integer contentformat: title: Content Format description: Identifies the content format for a Flow or Source using a URN string 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 - urn:x-nmos:format:multi deletionrequest: title: Deletion Request description: Describes an ongoing deletion request type: object required: - id - flow_id - timerange_to_delete - delete_flow - status properties: id: description: Deletion Request ID $ref: '#/components/schemas/uuid' flow_id: description: ID of the Flow to which the deletion request relates $ref: '#/components/schemas/uuid' timerange_to_delete: description: The timerange of Flow Segments to be deleted in this request, as described by the [TimeRange](#/schemas/timerange) type $ref: '#/components/schemas/timerange' timerange_remaining: description: The timerange of Flow Segments not yet deleted by this request, as described by the [TimeRange](#/schemas/timerange) type $ref: '#/components/schemas/timerange' delete_flow: description: Whether the Flow should be deleted once the timerange has been type: boolean created: description: Date/Time when this deletion request was created type: string format: date-time created_by: description: A string identifier for the entity that created the deletion request. Service implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system. type: string updated: description: Date/Time when this deletion request was updated type: string format: date-time expiry: description: Date/Time when this deletion request will be deleted type: string format: date-time status: description: Status of the delete request type: string enum: - created - started - done - error error: description: Provides more information for the error status, as described by the [Error](#/schemas/error) type $ref: '#/components/schemas/error' error: title: Error status metadata description: Provides more information for an error status. type: object required: - type - summary - time properties: type: description: The error type name. type: string summary: description: Summary description of the error and causes. type: string traceback: description: Stack trace leading to error (as a list of strings) type: array items: type: string time: description: Time at which the error ocurred, to aid in log correlation type: string format: date-time eventstreamcommon: title: Event Stream Mechanism description: Describes an event stream mechanism available in this service instance type: object required: - name properties: name: description: Name of this type of event stream mechanism. Must be unique. Any name defined in this specification is reserved type: string docs: description: Location (e.g. a URL) at which documentation for this event stream mechanism may be found type: string config: type: object description: Configuration options required to make use of this mechanism flowaudio: title: Audio Flow description: Describes an audio Flow type: object allOf: - $ref: '#/components/schemas/flowtechnical' - type: object required: - format - essence_parameters - codec properties: format: description: The primary content type URN for the Flow. type: string enum: - urn:x-nmos:format:audio essence_parameters: title: Audio Flow Essence Parameters description: Describes the parameters of the essence inside this audio Flow type: object required: - sample_rate - channels additionalProperties: false properties: sample_rate: description: The fixed number of samples per second. type: integer exclusiveMinimum: 0 channels: description: The channel count. type: integer exclusiveMinimum: 0 bit_depth: description: The number of significant bits used to represent the audio sample. The minumum number of bytes then equals `round_up(bit_depth / 8)`. If codec is `audio/x-raw-int` bit_depth must be set. If codec is `audio/x-raw-float` bit_depth must be set to 32 or 64 type: integer exclusiveMinimum: 0 codec_parameters: title: Audio Codec Parameters type: object required: [] properties: coded_frame_size: description: The fixed number of samples per coded audio frame. type: integer mp4_oti: description: The MPEG-4 Object Type Identification. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#mpeg-4_audio type: integer unc_parameters: title: Uncompressed Audio Parameters type: object required: - unc_type properties: unc_type: description: The uncompressed audio multi-channel representation type. If codec is `audio/x-raw-int` or `audio/x-raw-float`, unc_type must be set. type: string enum: - interleaved - planar - pairs init_segments: description: Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted. type: boolean flowcollection: title: Flow Collection description: Describes how Flows are collected into another Flow. Note that this is an ordered list. type: array items: type: object title: Flow Collection Item allOf: - $ref: '#/components/schemas/collectionitem' - type: object properties: container_mapping: description: Describes the mapping of the Flow essence from this Flow collection's container $ref: '#/components/schemas/containermapping' flowcommon: type: object description: Describes the core fields of a Flow (common properties to all Flows, imported by flow-get and flow-put specifications) title: Flow Common required: - id - source_id properties: id: description: Flow identifier $ref: '#/components/schemas/uuid' source_id: description: Source identifier $ref: '#/components/schemas/uuid' label: description: Freeform string label for the Flow. This should be a very short, human-readable label that may be displayed in listings of Flows. type: string description: description: Freeform text describing the Flow. 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`. type: string created_by: description: A string identifier for the entity that created the Flow. Service implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations. type: string updated_by: description: A string identifier for the entity that updated the Flow metadata most recently. Service implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations. type: string tags: description: 'Key value is a freeform string. WARNING: When updating a Flow with `tags` set, `tags` will be replaced with the provided dictionary. `tags` WILL NOT be merged with the provided values. When `tags` is not set in the request, `tags` will be unset (i.e. set to `{}`). To update individual tags, clients should use the [Create or Update Flow Tag](#/operations/PUT_flows-flowId-tags-name) endpoint.' $ref: '#/components/schemas/tags' metadata_version: description: A change to the Flow metadata, not including metadata_version, metadata_updated, segments_updated or Segments, results in a new version. If the metadata_version for Flow instances is identical then the metadata is identical. Service implementations SHOULD set suitable default values for `metadata_version` whenever Flow metadata is changed and `metadata_version` is either not set by the client, or set to it's existing value. Service implementations MAY permit clients to edit the value, subject to suitable permissions-based limitations. Where media is transfered between TAMS service instances without changing the Flow metadata, clients SHOULD maintain the `metadata_version`. To support this, service implementations SHOULD always accept the setting of `metadata_version` by the client on initial Flow creation. Service implementations SHOULD update this field where metadata is updated via child endpoints. Note that this specification places no requirements on incremental versioning. Service implementations may, for example, choose to use hashes or date-time version identifiers. type: string generation: description: An indication of how many lossy encodings the Flow content has been through. This parameter provides a hint to clients as to which is the "highest qualty" Flow available to them. A Flow with a higher generation may contain less of the original information than a flow with a lower generation. Where a Flow is captured straight from the orginating device (e.g. camera/microphone) in its highest quality, and there is no possibility of the content becoming available in a higher quality (e.g. via capture from ST2110 or SDI), it SHOULD have a `generation` of `0`. Where the originating device outputs multiple qualities of the Source, `generation` should represent the encoding processes each has been through as accurately as possible. type: integer minimum: 0 created: description: The date-time the Flow was created in a given context, e.g. in the service instance. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally type: string format: date-time metadata_updated: description: The date-time the Flow metadata was updated in a given context, e.g. in the service instance. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally type: string format: date-time segments_updated: description: The date-time the Flow Segments were updated in a given context, e.g. in the service instance. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally type: string format: date-time status: $ref: '#/components/schemas/flowstatus' read_only: description: 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. type: boolean max_bit_rate: description: The maximum bit rate of the Flow Segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote. type: integer minimum: 0 timerange: description: The timerange of samples available in the Flow, as described by the [TimeRange](../schemas/timerange#top) type. Service implementations MUST ignore this if given in a PUT request, and instead manage it internally. $ref: '#/components/schemas/timerange' flow_collection: description: List of Flows that are collected together by this Flow. $ref: '#/components/schemas/flowcollection' collected_by: type: array description: Flows that reference this Flow to include it in a collection. This attribute is intended to be read-only. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally items: $ref: '#/components/schemas/uuid' flowdata: title: Data Flow description: Describes a data Flow type: object allOf: - $ref: '#/components/schemas/flowtechnical' - type: object required: - format - essence_parameters - codec properties: format: description: The primary content type URN for the Flow. type: string enum: - urn:x-nmos:format:data essence_parameters: title: Data Flow Essence Parameters description: Describes the parameters of the essence inside this data Flow type: object additionalProperties: false properties: data_type: description: The type of information encoded in the Flow, identified using a URN. e.g. The data_type may be urn:x-tams:data:bounding-box, and the codec `application/json`. type: string init_segments: description: Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted. type: boolean flowget: title: Flow description: Describes a Flow type: object properties: profile_id: description: Profile identifier that was used to create the flow. $ref: '#/components/schemas/uuid' allOf: - $ref: '#/components/schemas/flowcommon' - oneOf: - $ref: '#/components/schemas/flowvideo' - $ref: '#/components/schemas/flowaudio' - $ref: '#/components/schemas/flowimage' - $ref: '#/components/schemas/flowdata' - $ref: '#/components/schemas/flowmulti' flowimage: title: Image Flow description: Describes a still image Flow, for use by thumbnail tracks etc type: object allOf: - $ref: '#/components/schemas/flowtechnical' - type: object required: - format - essence_parameters - codec properties: format: description: The primary content type URN for the Flow. type: string enum: - urn:x-tam:format:image essence_parameters: title: Image Flow Essence Parameters description: Describes the parameters of the essence inside this image Flow type: object required: - frame_width - frame_height additionalProperties: false properties: frame_width: description: The width of the picture in pixels. type: integer exclusiveMinimum: 0 frame_height: description: The height of the picture in pixels. type: integer exclusiveMinimum: 0 aspect_ratio: description: The display aspect ratio. i.e. display_width / display_height type: object required: - numerator - denominator properties: numerator: description: numerator type: integer exclusiveMinimum: 0 denominator: description: denominator type: integer exclusiveMinimum: 0 flowmulti: title: Multi-essence Flow description: Describes a multi-essence Flow type: object allOf: - $ref: '#/components/schemas/flowtechnical' - type: object required: - format properties: format: description: The primary content type URN for the flow. type: string enum: - urn:x-nmos:format:multi essence_parameters: title: Multi Flow Essence Parameters description: Describes the parameters of the essence inside this multi Flow type: object additionalProperties: false properties: init_segments: description: Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted. type: boolean flowput: type: object description: Describes a Flow title: Flow allOf: - $ref: '#/components/schemas/flowcommon' - oneOf: - type: object title: Flow Profile required: - profile_id properties: profile_id: description: Profile identifier that was used to create the flow. When supplying a profile_id no metadata which can be contained in a Profile should also be provided, doing so will result in a 400 validation error. Trying to create a Flow using a Profile ID that does not exist should also provide a 400 validation error $ref: '#/components/schemas/uuid' - $ref: '#/components/schemas/flowvideo' - $ref: '#/components/schemas/flowaudio' - $ref: '#/components/schemas/flowimage' - $ref: '#/components/schemas/flowdata' - $ref: '#/components/schemas/flowmulti' flowsegment: type: object description: Provides the location and metadata of the media files corresponding to timerange segments of a Flow. title: Flow Segment allOf: - type: object required: - object_id - timerange properties: object_id: description: The object store identifier for the Media Object. type: string ts_offset: description: The timestamp offset between the sample timestamps stored in the media file and the corresponding timestamp in the Segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](#/schemas/timestamp) type $ref: '#/components/schemas/timestamp' timerange: description: The timerange for the samples contained in the Segment. The timerange start is always inclusive. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](#/schemas/timerange) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline. $ref: '#/components/schemas/timerange' last_duration: description: The difference between the exclusive end of the `timerange` and the last sample timestamp. Format as described by the [Timestamp](#/schemas/timestamp) type, but cannot be negative $ref: '#/components/schemas/timestamp' object_timerange: description: The timerange covering the sample timestamps embedded in or derived from the Media Object itself, on the Media Object's timeline. $ref: '#/components/schemas/timerange' sample_offset: description: 'The start of the Segment represented as a count of samples from the start of the Media Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.' type: integer deprecated: true sample_count: description: 'The count of samples in the Segment (which may be fewer than in the Media Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.' type: integer deprecated: true init_object: title: Initialisation Object description: The Object containing the initialisation segment required to decode the parent Media Object. unevaluatedProperties: false allOf: - type: object required: - object_id properties: object_id: description: The identifier of the initialisation Object. type: string - $ref: '#/components/schemas/objectcore' - $ref: '#/components/schemas/objectmediacore' flowsegmentbulkfailure: title: Failed Segments description: List of Segments that have failed to register type: object required: - failed_segments properties: failed_segments: description: The list of Segments which have failed to register with the service instance type: array items: description: Failed Segment details type: object required: - object_id properties: object_id: description: The Object ID of the Segment which has failed to register with the service instance type: string timerange: description: The timerange of Segment that has failed, as described by the [TimeRange](#/schemas/timerange) type $ref: '#/components/schemas/timerange' error: description: Provides more information for the error status, as described by the [Error](#/schemas/error) type $ref: '#/components/schemas/error' flowsegmentpost: title: Flow Segment Post description: Provides the location and metadata of the media files corresponding to timerange Segments of a Flow. type: object required: - object_id - timerange properties: object_id: description: The Object identifier for the Media Object. The `content-type` of the Media Object MUST match the `container` mime-type of the Flow. Service implementations SHOULD reject Objects IDs which have previously been registered as an `init_object_id` on other Flow Segments. i.e. init segments may not be used as media segments. type: string init_object_id: description: The Object identifier for the initialisation segment Object required to decode the Media Object. The `content-type` of the initialisation segment Object MAY differ from the `container` mime-type of the Flow. This parameter MUST only be set where the media format makes use of initialisation segments. Initialisation Objects SHOULD be re-used where possible. This parameter SHOULD be omitted where the Object `object_id` already exists and is being re-used. Service implementations SHOULD reject Objects IDs which have previously been registered as an `id` on other Flow Segments. i.e. media segments may not be used as init segments. type: string ts_offset: description: The timestamp offset between the sample timestamps stored in, or inferred from, the media file and the corresponding timestamp in the Segment, ie. ts_offset = segment ts - media object ts. Assumed to be 0:0 if not set. Format as described by the [Timestamp](#/schemas/timestamp) type $ref: '#/components/schemas/timestamp' timerange: description: The timerange for the samples contained in the Segment. The timerange start is always inclusive. If samples have a duration then the timerange end is exclusive and covers at least the duration of the last sample. The exclusive timerange end will typically be set to the timestamp of the next sample. If the samples don't have a duration then the timerange end is inclusive. Format is described by the [TimeRange](#/schemas/timerange) type. Note that where temporal re-ordering is used, the timerange and samples refers to the presentation timeline. $ref: '#/components/schemas/timerange' object_timerange: description: The timerange covering the sample timestamps embedded in or derived from the Media Object itself, on the Media Object's timeline. If not given at first registration of an Object, defaults to `timerange - ts_offset` on the assumption that the Flow Segment uses the entire Media Object. Clients should not set this when Media Objects are re-used. Service implementations should reject requests where `object_timerange` is set to a value that conflicts with the existing Media Object metadata. $ref: '#/components/schemas/timerange' last_duration: description: The difference between the exclusive end of the `timerange` and the last sample timestamp. Format as described by the [Timestamp](#/schemas/timestamp) type, but cannot be negative $ref: '#/components/schemas/timestamp' sample_offset: description: 'The start of the Segment represented as a count of samples from the start of the Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. Assumed to be 0 if not set. Must be set if the Flow Segment doesn''t start at the beginning of the Media Object. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.' type: integer deprecated: true sample_count: description: 'The count of samples in the Segment (which may be fewer than in the Object). The count could be less than expected given the Segment duration and rate if there are gaps. If not set, every sample from sample_offset onwards is used. Must be set if the Flow Segment doesn''t use the entire Media Object. Note that a sample is a video frame or audio sample. A (coded) audio frame has multiple audio samples. DEPRECATED: Use object_timerange instead - see AppNote 0036. Service implementations SHOULD continue to store and return it if set.' type: integer deprecated: true get_urls: description: A list of URLs to which a GET request can be made to directly retrieve the contents of the Media Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat them as identical, however service instances may sort the list such that the preferred URL is first. `get_urls` should only be used to add uncontrolled URLs. URLs for the provided object_id controlled by the service instance will be populated automatically by the service instance. type: array items: type: object required: - url - label properties: url: description: A URL to which a GET request can be made to directly retrieve the contents of the Media Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint type: string label: description: Label identifying this URL. Service implementations should reject any requests using labels that are already associated with Storage Backends. Service implementations should reject any requests containing multiple `get_urls` with the same `label`. type: string key_frame_count: description: The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point type: integer flowstatus: title: Flow Status description: 'The current ingest status of a Flow. Available values are as follows. `awaiting_content` - Flow is expecting, but not currently receiving content. `ingesting` - Content is currently being ingested. `replication_in_progress` - Content is currently being ingested to this Flow from another Service Instance via a replication process. `closed_complete` - Flow is complete and will not receive any more content. NOTE: Because this parameter is maintained/updated by a Client, the value of this parameter is only indicative and not authoritative. If the Client ingesting the content becomes unavailable, it may leave this parameter in an incorrect state. Clients should aim to tidy up this state appropriately once they recover. Service Implementers MAY consider adding more active management of the `status` of Flows to mitigate Clients failing to tidy up on completion/failure, as part of more general lifecycle management capability, in line with the approach described for [retention management](https://github.com/bbc/tams/blob/main/docs/appnotes/0019-implementing-retention-management.md). But Clients should not assume such capability.' type: string enum: - awaiting_content - ingesting - replication_in_progress - closed_complete flowstorage: type: object title: Media Bucket Object Store description: Gives information on storage for Objects. This schema is for the `http_object_store` Storage Backend type which provides URLs for storing Objects in object store buckets, and is the only Storage Backend type currently implemented. URLs SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details. Where included in the response, `content-type` MUST match the corresponding value in the request. properties: media_objects: type: array description: List of information for identifying and uploading Objects items: type: object description: Information for a Object required: - object_id - put_url properties: object_id: description: The object store identifier for the Object. type: string put_url: $ref: '#/components/schemas/httprequest' presigned: description: If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema). type: boolean additionalProperties: false flowstoragepost: title: Flow Storage Post description: Post data for the Flow storage endpoint type: object properties: limit: description: Limit the number of Objects in each response page. Service implementations may specify their own default and maximum for the limit type: integer object_ids: description: Array of object_ids to use. The supplied object_ids must be new and not already in use in this TAMS service instance. A 400 response will be returned if any supplied object_id already exists. type: array items: type: string storage_id: description: The Storage Backend to allocate storage in. A Storage Backend identifier as advertised at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint. If not set the default, as advertised at the [/service/storage-backends](#/operations/GET_storage-backends) endpoint, will be used if available. An invalid Storage Backend identifier will result in a 400 error. $ref: '#/components/schemas/uuid' content_type: description: The `content_type` to use for the Objects. This parameter MUST only be set where requesting storage for initialisation segments in media formats which require them, and where the mime-type of those initialisation segments differs to that of the media segments. Assumed to be the `container` type of the Flow if not set. $ref: '#/components/schemas/mimetype' presigned: description: If set to `true`, the `put_url`s in the response will be presigned. If set to `false`, the `put_url`s in the response will not be presigned. 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. Services may choose their own default. If Clients only support one mode of operation, they SHOULD specify this parameter. type: boolean not: allOf: - required: - limit - required: - object_ids flowtechnical: title: Flow Technical description: Describes the technical characteristics of a Flow (imported by type-specific specifications or as part of a profile) type: object properties: codec: description: A MIME type identification of the (lossy or lossless) coding used for the Flow content. Note that the `type` component of the container MIME type (i.e. the component before the `/`) may be different to the `type` component of the codec MIME type. e.g. An audio Flow may have `audio/aac` coded content may be wrapped in a `video/mp2t` container. Mime types from the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml) should be preferred. Where multiple MIME types are possible, the most common should be preferred. Where this is insufficient, the maintainers of the TAMS repository may create an application note advising which MIME type to use. type: string pattern: ^[^\s/]+/[^\s/]+$ container: description: The container MIME type for Flow Segments. Note that the `type` component of the container MIME type (i.e. the component before the `/`) may be different to the `type` component of the codec MIME type. e.g. An audio Flow may have `audio/aac` coded content may be wrapped in a `video/mp2t` container. Where multiple types exist for a subtype (e.g. `video/mp4`, `audio/mp4`, `application/mp4`), the closest MIME type to the Flow `format` should be used (e.g. `audio/mp4` for a Flow `format` of `urn:x-nmos:format:audio`). Mime types from the [IANA registry](https://www.iana.org/assignments/media-types/media-types.xhtml) should be preferred. Where multiple MIME types are possible, the most common should be preferred. Where this is insufficient, the maintainers of the TAMS repository may create an application note advising which MIME type to use. type: string pattern: ^[^\s/]+/[^\s/]+$ avg_bit_rate: description: The average bit rate of the Flow Segments in 1000 bits/second. A precise definition can be found in the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote. type: integer minimum: 0 segment_duration: description: The target Flow Segment duration in seconds. The duration for each Segment may vary around this target value. See also the [Setting Flow Bit Rate Properties](https://github.com/bbc/tams/blob/main/docs/appnotes/0013-setting-flow-bit-rate-properties.md) AppNote for how this property can be used to calculate buffer sizes. type: object required: - numerator properties: numerator: description: numerator type: integer exclusiveMinimum: 0 denominator: description: denominator type: integer default: 1 exclusiveMinimum: 0 container_mapping: description: Describes the mapping of the Flow essence from the this Flow's container $ref: '#/components/schemas/containermapping' flowvideo: title: Video Flow description: Describes a video Flow type: object allOf: - $ref: '#/components/schemas/flowtechnical' - type: object required: - format - essence_parameters - codec properties: format: description: The primary content type URN for the Flow. type: string enum: - urn:x-nmos:format:video essence_parameters: title: Video Flow Essence Parameters description: Describes the parameters of the essence inside this video Flow type: object required: - frame_width - frame_height unevaluatedProperties: false properties: frame_width: description: The width of the picture in pixels. type: integer exclusiveMinimum: 0 frame_height: description: The height of the picture in pixels. type: integer exclusiveMinimum: 0 bit_depth: description: The number of significant bits used to represent the video component sample. If codec is `video/raw`, bit_depth must be set. type: integer exclusiveMinimum: 0 interlace_mode: description: Interlaced video mode for frames in this Flow type: string enum: - progressive - interlaced_tff - interlaced_bff - interlaced_psf colorspace: description: Colorspace used for the video type: string enum: - BT601 - BT709 - BT2020 - BT2100 transfer_characteristic: description: Transfer characteristic type: string enum: - SDR - HLG - PQ aspect_ratio: description: The display aspect ratio. i.e. display_width / display_height type: object required: - numerator - denominator properties: numerator: description: numerator type: integer exclusiveMinimum: 0 denominator: description: denominator type: integer exclusiveMinimum: 0 pixel_aspect_ratio: description: The pixel aspect ratio. This is usually 1:1 (i.e. square pixels) for modern video. Some, usually older, video formats use non-square pixels e.g. some Standard Definition video. This is where that may be indicated. type: object required: - numerator - denominator properties: numerator: description: numerator type: integer exclusiveMinimum: 0 denominator: description: denominator type: integer exclusiveMinimum: 0 component_type: description: Picture component representation. type: string enum: - YCbCr - RGB horiz_chroma_subs: description: Horizontal chroma component sub-sampling. When unc_type is set to a YUV type, horiz_chroma_subs must be set. type: integer exclusiveMinimum: 0 vert_chroma_subs: description: Vertical chroma component sub-sampling. When unc_type is set to a YUV type, vert_chroma_subs must be set. type: integer exclusiveMinimum: 0 unc_parameters: title: Uncompressed Video Parameters type: object required: - unc_type properties: unc_type: description: Uncompressed picture packing type. If codec is `video/raw`, unc_type must be set. type: string enum: - planar - YUYV - UYVY - AYUV - v210 - v216 - RGB - RGBx - xRGB - BGRx - xBGR - RGBA - ARGB - BGRA - ABGR - alpha avc_parameters: title: AVC Codec Parameters type: object required: - profile - level - flags properties: profile: description: AVC / H.264 profile byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter type: integer level: description: AVC / H.264 level byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter type: integer flags: description: AVC / H.264 flags byte. For more information on the use of this property in codec strings, see https://developer.mozilla.org/en-US/docs/Web/Media/Formats/codecs_parameter#using_the_codecs_parameter type: integer frame_rate: title: Fixed Frame Rate description: The fixed number of frames per second. MUST be set if `vfr` is `false` or omitted. MUST NOT be set if `vfr` is `true`. type: object required: - numerator properties: numerator: description: numerator type: integer exclusiveMinimum: 0 denominator: description: denominator type: integer default: 1 exclusiveMinimum: 0 vfr: description: If `true`, the frame rate of the Flow is variable and `frame_rate` MUST NOT be set. If `false` or omitted, the frame rate of the Flow is fixed and `frame_rate` MUST be set. type: boolean default: false init_segments: description: Whether the Flow makes use of initialisation segments. This parameter MUST be set to `true` if Media Objects have `init_object` populated. If set to `true`, all Media Objects MUST have `init_object` populated. Assume `false` if omitted. type: boolean if: properties: vfr: enum: - false - null then: required: - frame_rate else: not: required: - frame_rate httprequest: title: HTTP Request description: Gives information on a particular http request a client should perform type: object required: - url properties: url: description: The URL to make the request to. Where this URL is pre-signed, it SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema). type: string body: description: The text of the body which needs to be included in the request type: string content-type: description: The content type which must be used type: string headers: description: Additional headers that should be included type: object additionalProperties: type: string additionalProperties: true mimetype: title: MIME Type description: A Mime Type without parameters as defined in [RFC2045](https://www.rfc-editor.org/rfc/rfc2045#section-5.1) and [RFC7231](https://www.rfc-editor.org/rfc/rfc7231#section-3.1.1.1) type: string pattern: ^(application|audio|font|example|image|message|model|multipart|text|video|x-(?:[0-9A-Za-z!#$%&'*+.^_`|~-]+))/([0-9A-Za-z!#$%&'*+.^_`|~-]+)$ object: title: Object unevaluatedProperties: false allOf: - type: object required: - id - referenced_by_flows properties: id: description: The Object identifier. type: string referenced_by_flows: type: array description: List of Flows that reference this Object via Flow Segments in this store instance. For init Objects, this reference is indirect via Media Objects. items: $ref: '#/components/schemas/uuid' first_referenced_by_flow: description: The first Flow that had a Flow Segment reference the Object in this store instance. For init Objects, this reference is indirect via Media Objects. This Flow is also present in 'referenced_by_flows' if it is still referenced by the Flow. This property is optional and may in some implementations become unset if the Flow no longer references the Object, e.g. because it was deleted. $ref: '#/components/schemas/uuid' timerange: description: The timerange covering the sample timestamps embedded in or derived from the Object itself, on the Media Object's timeline. This parameter MUST be set where the Object contains media. It MUST NOT be set where the Object contains an init segment. $ref: '#/components/schemas/timerange' init_object: title: Initialisation Object description: The Object containing the initialisation segment required to decode the parent Media Object. unevaluatedProperties: false allOf: - type: object required: - id properties: id: description: The identifier of the initialisation Object. type: string - $ref: '#/components/schemas/objectcore' - $ref: '#/components/schemas/objectmediacore' objectcore: type: object description: Provides the location and metadata of the files corresponding to a Object. title: Object properties: get_urls: description: A list of URLs to which a GET request can be made to directly retrieve the contents of the Object. This is required by the `http_object_store` Storage Backend type, which is the only one currently described. Clients may choose any URL in the list and treat the content returned as identical, however servers may sort the list such that the preferred URL is first. Storage Backend metadata for controlled URLs should be populated by the TAMS instance based on the Storage Backend the Object instance resides in. type: array items: type: object unevaluatedProperties: false allOf: - $ref: '#/components/schemas/storagebackend' - type: object required: - url properties: storage_id: description: Storage Backend identifier $ref: '#/components/schemas/uuid' url: description: A URL to which a GET request can be made to directly retrieve the contents of the Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint. This URL SHOULD support the inclusion of checksums in headers as supported by advertised Storage Backend product. See AppNote 0048 for more details. type: string presigned: description: If `true`, this URL is pre-signed. If this parameter is unset, the URL is NOT pre-signed. The presigned URL SHALL remain valid for the timeframe advertised in [`min_presigned_url_timeout` at the `/service`](#/operations/GET_service) endpoint, which is subject to a specified minimum (see service endpoint schema). type: boolean label: description: Label identifying this URL. If the URL is controlled by the service instance, this is the Storage Backend's label. If the URL is uncontrolled, this is the label provided when a client registered the URL. If the 'label' is not set then this URL can't be filtered for using the 'accept_get_urls' API query parameter. type: string controlled: description: If `true`, this URL is on a Storage Backend controlled by this service instance. If `false`, this URL is uncontrolled and does not have it's lifecycle managed by this instance. If this parameter is unset, assume `true`. type: boolean objectmediacore: type: object description: Provides the location and metadata of the media files corresponding to a Media Object. title: Object allOf: - properties: key_frame_count: description: The number of key frames in the Media Object. This should be set greater than zero when the Media Object contains key frames that serve as a stream access point type: integer - $ref: '#/components/schemas/objectcore' objectsinstancespost: type: object description: Register a Object instance in the store. title: Object registration oneOf: - description: Request the duplication of a Object instance to a new Storage Backend, via it's `storage_id`. title: Controlled instance type: object required: - storage_id properties: storage_id: description: Storage backend identifier $ref: '#/components/schemas/uuid' - description: Register an uncontrolled Object instance via its `url`. title: Uncontrolled instance type: object required: - url - label properties: url: description: A URL to which a GET request can be made to directly retrieve the contents of the Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint type: string label: description: Label identifying this Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends. type: string profile: type: object description: Describes a Profile title: Profile required: - id - flow_metadata properties: id: description: Profile identifier. $ref: '#/components/schemas/uuid' label: description: Freeform string label for the Profile. type: string description: description: Freeform text describing the Profile. type: string created_by: description: A string identifier for the entity that created the Profile. Implementations SHOULD set suitable default values for `created_by` based on the principal accessing the system, and MAY permit clients to edit the value, subject to suitable permissions-based limitations. type: string created: description: The date-time the Profile was created in a given context, e.g. in the store. Implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. type: string format: date-time tags: description: Key value is a freeform string. As Profiles are considered immutable then this also applies to tags which cannot be updated after a Profile has been created. $ref: '#/components/schemas/tags' flow_metadata: description: The technical characteristics of the Profile. This section will be mapped directly to all flows created using this Profile. type: object oneOf: - title: Video Flow description: The technical characteristics of the Profile. This section will be mapped directly to all flows created using this Profile. $ref: '#/components/schemas/flowvideo' - title: Audio Flow description: The technical characteristics of the Profile. This section will be mapped directly to all flows created using this Profile. $ref: '#/components/schemas/flowaudio' - title: Image Flow description: The technical characteristics of the Profile. This section will be mapped directly to all flows created using this Profile. $ref: '#/components/schemas/flowimage' - title: Data Flow description: The technical characteristics of the Profile. This section will be mapped directly to all flows created using this Profile. $ref: '#/components/schemas/flowdata' service: title: Service description: Provides information about the service instance type: object required: - type - api_version - min_object_timeout properties: name: description: The service instance name. This should be a very short, human-readable name that may be displayed in listings of Service instances. type: string description: description: The service instance description. This should be a human-readable description that may be showed in detailed views of Service instances. The description should be longer and more detailed than `name`. type: string type: description: The type identifier for the service instance. The value must start with 'urn:x-tams:service' type: string api_version: description: The version of the TAMS API specification this service instance implements type: string pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)$ service_version: description: 'The version of software providing this service. Note: Different implementations and software houses may use different conventions for their version identification. As such, this field is intentionally permissive and intended to be informative only. Client implementations should avoid using this field to determine compatibility.' type: string event_stream_mechanisms: description: List the types of event stream that this service implementation supports type: array items: $ref: '#/components/schemas/eventstreamcommon' min_object_timeout: description: The minimum timeframe within which a Object created by this service must be registered against a Flow segment before it is garbage collected. Services SHOULD allow a small grace period beyond the advertised value to account for latency in assigning the Objects and returning them to the Client. This timeout MUST be `300:0` (i.e. 5 minutes) or greater. Clients MUST be capable of reaching this minimum performance level. Clients SHOULD adapt to this value by balancing how many object URLs to request per page against how fast they will be used. Services MAY allow this value to be configured at deploy-time. Format as described by the [Timestamp](#/schemas/timestamp) type. For more infomation, see the documentation of the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage) endpoint. $ref: '#/components/schemas/timestamp' min_presigned_url_timeout: description: The minimum timeframe within which pre-signed URLs generated by this Service are valid for (both for writing and reading content). This attribute MUST be set on implementations that support pre-signed URLs. Services SHOULD allow a small grace period beyond the advertised value to account for latency in generating pre-signed URLs and returning them to the Client. This timeout MUST be `30:0` (i.e. 30 second) or greater. The value of this parameter MUST be equal or less than `min_object_timeout` to avoid Objects being garbage collected while their pre-signed PUT URLs are still valid. Clients MUST be capable of reaching this minimum performance level. Clients SHOULD adapt to this value, by taking care to request URLs that will be used in a timely manner. Services MAY allow this value to be configured at deploy-time. Format as described by the [Timestamp](#/schemas/timestamp) type. $ref: '#/components/schemas/timestamp' servicepost: title: Update Service Info description: Post update to the service info type: object properties: name: description: The service instance name type: string description: description: The service instance description type: string source: title: Source description: |- Describes a Source: an abstract representation of a piece of media as defined in Sources may be elemental (and represented directly by a Flow), or may represent a collection of other Sources, e.g. a Source collecting video and audio together. type: object required: - id - format properties: id: description: Source identifier $ref: '#/components/schemas/uuid' format: description: The primary content type URN for the Source. $ref: '#/components/schemas/contentformat' label: description: Freeform string label for the Source. This should be a very short, human-readable label that may be displayed in listings of Sources. type: string description: description: Freeform text describing the Source. 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`. type: string created_by: description: A string identifier for the entity that created the Source. Service implementations SHOULD set suitable default values for `created_by` based on the principal accessing the systems. type: string updated_by: description: A string identifier for the entity that updated the Source metadata most recently. Service implementations SHOULD set suitable default values for `updated_by` based on the principal accessing the system. type: string created: description: The date-time the Source was created in a given context, e.g. in the service instance. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally type: string format: date-time updated: description: The date-time the Source metadata was last updated in a given context, e.g. in the service instance. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally type: string format: date-time tags: $ref: '#/components/schemas/tags' source_collection: description: List of Sources that are collected together by this Source. This attribute is intended to be read-only. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions. type: array items: $ref: '#/components/schemas/collectionitem' collected_by: description: Sources that reference this Source to include it in a collection. This attribute is intended to be read-only. Service implementations SHOULD ignore this if given in a PUT request, and instead manage it internally. Source collections can be inferred from Flow collection definitions. type: array items: $ref: '#/components/schemas/uuid' storagebackend: title: Storage Backend description: Provides technical, and logic metadata about a storage backend type: object properties: store_type: description: The generic Storage Backend type. Used to identify the required workflow for reading and writing media. Any `store_product` should be compatible, as much is required for basic interoperability between TAMS implementations, with their associated generic `store_type`. type: string enum: - http_object_store provider: description: The cloud (or other) provider of the Storage Backend type: string region: description: The region in the cloud this Storage Backend resides type: string availability_zone: description: The availability zone in the cloud region this Storage Backend resides. Note that many cloud providers randomize availability zone identifiers such that they are consistent within a cloud account, but not necessarily between accounts. Caution should be exercised when using this parameter. type: string store_product: description: The storage product name. type: string tags: description: Key value is a freeform string. $ref: '#/components/schemas/tags' storagebackendslist: title: Storage Backends List description: Information about the storage backends available on this service instance. type: array items: allOf: - $ref: '#/components/schemas/storagebackend' - required: - store_type - provider - store_product - id - type: object properties: id: description: Storage backend identifier $ref: '#/components/schemas/uuid' label: description: Freeform string label for a storage backend. type: string default_storage: description: If set to `true`, this is the default storage backend. The default storage backend will be used if the client does not specify a storage backend id when requesting the allocation of storage. If this parameter is not set, assume `false`. Service instances may either set one storage backend as default, or none - indicating that clients must always specify a storage backend. type: boolean additionalProperties: false tags: title: Tags description: Key is a freeform string. Value is a freeform string, or an array of freeform strings. type: object additionalProperties: anyOf: - type: string - type: array items: type: string timerange: title: TimeRange description: | A timerange of timestamps. It is represented using one or two timestamps with inclusivity and exclusivity markers. E.g. * `[0:0_10:0)` represents 10 seconds of media starting at timestamp `0:0` and ending before `10:0`. * `(5:0_` represents a timerange starting after `5:0` and to eternity. * `_` without timestamps or inclusivity markers represents "eternity" (i.e. the entire timeline). * `()` without timestamps represents "never" (i.e. a range of zero length in no particular position). * `[1694429247:0_1694429248:0)` is a 1 second TAI timerange starting at 2023-09-11T10:46:50.0Z UTC. * `[1694429247:0]` is an instantaneous TAI timerange at 2023-09-11T10:46:50.0Z UTC. This is equivalent to `[1694429247:0_1694429247:0]`. The short syntax is preferred due to ease of identification as instantaneous. Instantaneous TimeRanges cannot use exclusive markers (i.e. `(` or `)`). * A `[` or `]` indicates that bound is inclusive, and a `(` or `)` indicates that bound is exclusive. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note. type: string pattern: ^(\[|\()?(-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8}))?(_(-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8}))?)?(\]|\))?$ timestamp: title: Timestamp description: | A signed nanosecond resolution timestamp represented as "{sign?}{seconds}:{nanoseconds}". The intended interpretation of the value is assumed to be defined elsewhere. E.g. * "1:40000000" is the timestamp of the 27th video frame for 25 Hz video with origin at "0:0". * "1694429247:40000000" is the TAI timestamp for a video frame at 2023-09-11T10:46:50.04Z UTC. Details of the format can be found in the [Timestamps in TAMS](https://github.com/bbc/tams/blob/main/docs/appnotes/0008-timestamps-in-TAMS.md) application note. type: string pattern: ^-?(0|[1-9][0-9]*):(0|[1-9][0-9]{0,8})$ urllabellist: title: Query String GET URL Label list description: A list of Object GET URL Labels, formatted for use in query string parameters type: string pattern: ^([^,]+(,[^,]+)*)?$ urltaglist: title: Query String Tag value list description: A list of tag values, formatted for use in query string parameters type: string pattern: ^([^,]+(,[^,]+)*)?$ uuid: title: UUID description: A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562) 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}$ uuidlist: title: Query String UUID list description: A list of Universally Unique Identifiers (UUIDs) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562), formatted for use in query string parameters 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})*$ uuidlistempty: title: Query String UUID list (optionally empty) description: A list of Universally Unique Identifiers (UUIDs) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562), formatted for use in query string parameters, or an empty string. An empty value selects resources that are not in any collection. 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})*)?$ webhook: title: Register Webhook description: Register to receive updates via webhook type: object required: - url - events properties: url: description: The URL to which the service instance should make HTTP POST requests with event data type: string api_key_name: description: The HTTP header name that is added to the event POST type: string events: description: List of event types to receive type: array items: type: string enum: - flows/created - flows/updated - flows/deleted - flows/segments_added - flows/segments_deleted - sources/created - sources/updated - sources/deleted flow_ids: description: Limit Flow and Flow Segment events to Flows in the given list of Flow IDs type: array items: $ref: '#/components/schemas/uuid' source_ids: description: Limit Flow, Flow Segment and Source events to Sources in the given list of Source IDs type: array items: $ref: '#/components/schemas/uuid' flow_collected_by_ids: description: Limit Flow and Flow Segment events to those with a Flow that is collected by a Flow Collection in the given list of Flow Collection IDs. An empty array limits events to Flows that are not collected by any Flow Collection. type: array items: $ref: '#/components/schemas/uuid' source_collected_by_ids: description: Limit Flow, Flow Segment and Source events to those with a Source that is collected by a Source Collection in the given list of Source Collection IDs. An empty array limits events to Sources that are not collected by any Source Collection. type: array items: $ref: '#/components/schemas/uuid' accept_get_urls: description: List of labels of URLs to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_get_urls` query parameter for the [/flows/{flowId}/segments](#/operations/GET_flows-flowId-segments) API endpoint, except that the labels are represented using a JSON array rather than a (comma separated list) string. type: array items: type: string accept_storage_ids: description: List of labels of `storage_id`s to include in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `accept_storage_ids` query parameter for the [/flows/{flowId}/segments](#/operations/GET_flows-flowId-segments) API endpoint, except that the IDs are represented using a JSON array rather than a (comma separated list) string. type: array items: $ref: '#/components/schemas/uuid' presigned: description: Whether to include presigned/non-presigned URLs in the `get_urls` property in `flows/segments_added` events. Where multiple `get_urls` filter query parameters are provided, the included `get_urls` will match all filters. This option is the same as the `presigned` query parameter for the [/flows/{flowId}/segments](#/operations/GET_flows-flowId-segments) API endpoint. type: boolean verbose_storage: description: Whether to include storage metadata in the `get_urls` property in `flows/segments_added` events. This option is the same as the `verbose_storage` query parameter for the [/flows/{flowId}/segments](#/operations/GET_flows-flowId-segments) API endpoint. type: boolean include_object_timerange: description: If set to `true`, the underlying object's timerange should appear in `flows/segments_added` events. Assume `false` if omitted. This option is the same as the `include_object_timerange` query parameter for the [/flows/{flowId}/segments](#/operations/GET_flows-flowId-segments) API endpoint. type: boolean tags: $ref: '#/components/schemas/tags' webhookget: title: Webhook Detail description: Describes a Webhook type: object allOf: - $ref: '#/components/schemas/webhookwithid' - type: object required: - status properties: error: description: Provides more information for the error status, as described by the [Error](#/schemas/error) type. Amongst other conditions, implementations MAY use this field to indicate failure to deliver webhooks resulting in return codes other than the 200 Success described in the the webhook event schemas. $ref: '#/components/schemas/error' status: description: Status of the Webhook. `created` indicates the webhook has been successfully registered but is yet to begin sending events or, depending on the service implementation, the worker responsible for sending the events has yet to start. `started` indicates the webhook is active and sending events. `disabled` indicates the webhook has been disabled by a client and is not currently sending events. `error` indicates an error condition has been encountered and the webhook has been disabled by the service instance. More information about the error condition will be indicated by the service instance in the `error` parameter. Service implementations SHOULD implement appropriate retries and only enter the `error` state when absolutely necesary. A webhook in the `error` or `disabled` state may be re-enabled by a client by setting the status to `created`. A webhook in the `created` or `started` state may be disabled by a client by setting the status to `disabled`. Attempting to transition an `error` status to `disabled` SHOULD be rejected. type: string enum: - created - started - disabled - error webhookpost: title: Register Webhook description: Register to receive updates via webhook type: object allOf: - $ref: '#/components/schemas/webhook' - type: object properties: api_key_value: description: The value that the HTTP header 'api_key_name' will be set to type: string status: description: Status of the Webhook. `created` will register the webhook in the created state and the service instance will attempt to start sending events. `disabled` will register the webhook in a disabled state and will not send events. Assumed to be `created` if not set. type: string enum: - created - disabled webhookput: title: Modify Webhook description: Modify existing webhook type: object allOf: - $ref: '#/components/schemas/webhookwithid' - type: object required: - status properties: api_key_value: description: The value that the HTTP header 'api_key_name' will be set to type: string status: description: Status of the Webhook. `created` indicates the webhook has been successfully registered but is yet to begin sending events or, depending on the service implementation, the worker responsible for sending the events has yet to start. `started` indicates the webhook is active and sending events. `disabled` indicates the webhook has been disabled by a client and is not currently sending events. `error` indicates an error condition has been encountered and the webhook has been disabled by the service instance. More information about the error condition will be indicated by the service instance in the `error` parameter. Service implementations SHOULD implement appropriate retries and only enter the `error` state when absolutely necesary. A webhook in the `error` or `disabled` state may be re-enabled by a client by setting the status to `created`. A webhook in the `created` or `started` state may be disabled by a client by setting the status to `disabled`. Attempting to transition an `error` status to `disabled` SHOULD be rejected. type: string enum: - created - disabled webhookwithid: title: Webhook Details description: Details of an existing registered webhook type: object allOf: - $ref: '#/components/schemas/webhook' - type: object required: - id properties: id: description: Webhook identifier $ref: '#/components/schemas/uuid' 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