{ "openapi": "3.0.0", "info": { "title": "API Endpoint Reference", "description": "\n\nTenovos has introduced version 1.5 to provide non-breaking improvements over previous versions.\n\nKey Changes:\n * Authentication Standards now include OAuth2 code flow. \n * Client ID is no longer required to be passed when requesting an Authorization token using our Standard Auth from v1.4 \n * New endpoints have been added and will continue to be added until v2 is generally available to all customers.\n * Adaptive Template endpoints\n * A new Get Asset endpoint with a simplified Response\n * A new Create Asset endpoint with simplified payloads for the Request and Response\n * A new Update Asset endpoint with simplified payloads for the Request and Response\n * Metadata Admin API endpoints for managing Attributes, Groups, and Templates\n * We've made some performance improvements to most endpoints\n", "termsOfService": "https://tenovos.com/terms-of-service", "contact": { "email": "product@tenovos.com" }, "license": { "name": "Tenovos Active Story Management", "url": "https://www.tenovos.com/" }, "version": "1.5" }, "externalDocs": { "description": "Find out more about Tenovos", "url": "https://tenovos.com" }, "servers": [ { "url": "https://api.uat.tenovos.io/v1" }, { "url": "https://api.tenovos.io/v1" } ], "security": [ { "ApiKeyAuth": [] }, { "BasicAuth": [] } ], "tags": [ { "name": "ACTIONS", "description": "Invoke the Action API to retrieve information about invoked Actions." }, { "name": "ADAPTIVE TEMPLATES", "description": "Invoke the API to retrieve information about invoked Actions." }, { "name": "ASSETS", "description": "Invoke the Asset API to create, retrieve, manipulate, and share Assets. This API also provides operations to manage Asset relationships and download Asset content." }, { "name": "AUTHENTICATION", "description": "Invoke the Authentication API to generate, refresh, and revoke access tokens. An access token is required to perform any authorized API operation." }, { "name": "CDN (Coming Soon!)", "description": "Tenovos Content Delivery Network (CDN) - Coming Soon!\n\nTenovos CDN: Pull Zone Overview\n\nTenovos CDN provides global content acceleration and optimization through a pull zone architecture, ensuring that your assets are delivered to end users with maximum speed, reliability, and efficiency. A Content Delivery Network (CDN) works by caching\nstatic content—such as images, videos, and other media—on servers distributed across the globe. When an asset is requested, the CDN serves it from the nearest edge location, reducing load times and offloading traffic from the origin server, which in this case is Tenovos DAM.\n\nA pull zone is the core mechanism that powers this system. It automatically fetches content from the origin the first time it is requested, then caches it at the edge. Subsequent requests are served directly \nfrom the CDN cache, improving response times and reducing bandwidth consumption.\n\nThrough the Tenovos CDN API, you can create, update, and manage pull zones programmatically. Pull zones support advanced features such as global edge caching, cache purging, bandwidth controls, and real-time performance statistics like cache \nhit rate and geographic request distribution. Optional optimization settings allow you to enhance performance further by enabling image compression, WebP and AVIF support, and content minification.\n\nWith just a few API calls, you can fully integrate high-performance content delivery into your Tenovos workflows—no complex infrastructure required. " }, { "name": "COLLECTIONS", "description": "Invoke the Collection API to create, retrieve, edit, and delete Collections. Collections are used to group and catalog related Assets for quick access and consumption. Collections can be configured as:\n - private: Visible only to the user who created the Collection.\n - secured: Visible to users with.\n\nWhen retrieving the Assets within a Collection, the requesting user will only see the Assets that the user has access to view. For example, a librarian may see all Assets within a Collection, but a general consumer user may only see a portion of those Assets, due to limited security access." }, { "name": "METADATA ATTRIBUTES", "description": "Invoke the Metadata Attributes API to retrieve Metadata Attributes, and to create, read, update, and delete Metadata Attribute definitions. Metadata Attributes come in varying types, including Text, Date, Controlled Vocabulary, Tabular, and Cascading, and can be assigned to Metadata Groups and Templates.\n\n**Admin Endpoints (NEW!):** Create, read, update, and delete Metadata Attributes. These endpoints require the Metadata Management admin privilege." }, { "name": "METADATA GROUPS", "description": "Invoke the Metadata Groups API to create, read, update, and delete Metadata Groups. A Metadata Group organizes related Metadata Attributes together for use within a Metadata Template.\n\n**Admin Endpoints (NEW!):** These endpoints require the Metadata Management admin privilege." }, { "name": "METADATA TEMPLATES", "description": "Invoke the Metadata Templates API to create, read, update, and delete Metadata Templates, and to apply Metadata definition changes. A Metadata Template defines a set of Metadata Attributes that, when assigned to an Asset, become available for population on that Asset.\n\n**Admin Endpoints (NEW!):** Create, read, update, and delete Metadata Templates. These endpoints require the Metadata Management admin privilege." }, { "name": "METADATA VOCABULARIES", "description": "Invoke the Controlled Vocabularies API to create, retrieve, update, and delete Controlled Vocabularies used to constrain the values available to a Metadata Attribute." }, { "name": "METADATA CASCADES", "description": "Invoke the Metadata Cascades API to create, retrieve, update, and delete Cascading Attributes, a Metadata Attribute type whose available values depend on the value selected in a parent Attribute." }, { "name": "METADATA TABLES", "description": "Invoke the Metadata Tables API to create, retrieve, update, and delete Tabular Attributes, a Metadata Attribute type that stores structured, multi-column data on an Asset." }, { "name": "SEARCH", "description": "Search for Collections by Collection name.\n\nPerform Asset searches using keywords or Attribute-specific search terms using the Keyword Search endpoint.\n\nPerform a scan on all assets based on search criteria using a cursor to page through the entire result set of assets." }, { "name": "REQUESTS", "description": "Invoke these API's to create new Requests and manage existing Requests." }, { "name": "SECURITY ROLES", "description": "Invoke the Security Roles API to retrieve, create, update, and delete Security Roles, and to retrieve the Permissions and Privileges that can be assigned to a Role to control what a user can see and do across the platform." }, { "name": "SECURITY TEMPLATES", "description": "Invoke the Security Templates API to retrieve, create, update, and delete Security Templates. A Security Template combines Security Roles and User Groups to define access to Assets and other objects in the platform." }, { "name": "SECURITY GROUPS", "description": "Invoke the Security User Groups API to retrieve, create, update, and delete Security User Groups used to organize users for the purpose of assigning security access." }, { "name": "USERS", "description": "Invoke the User API to retrieve User profile information." }, { "name": "STORY BOARDS", "description": "Invoke the Story Boards API to retrieve and manage Story Boards. Story Boards are curated content experiences that combine collections, saved searches, and other content blocks into a single shareable view.\n\n**Coming Soon:** Additional endpoints for creating, updating, and deleting Story Boards." }, { "name": "WEBHOOKS", "description": "Tenovos Webhook Subscriptions\n\nFor more information about our Webhooks, see the [Webhook section](/developer-portal/webhooks/overview) of our Developer Portal\n" }, { "name": "RIGHTS MANAGEMENT", "description": "Invoke the Rights Management API to manage rights-management associations between Projects, Agreements, Entities, and Rights." } ], "paths": { "/action/{id}": { "get": { "operationId": "GetAction", "tags": [ "ACTIONS" ], "summary": "Action Details", "description": "Retrieve an Action by specifying an **Object ID** or **File ID** in the request path.\n\nThe user requesting the Action must have view access to the Action in order to retrieve the Action.\n\n**Average Response Time:** 146ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Action **Object ID** or **File ID**", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid", "maxLength": 36, "minLength": 36, "x-nullable": false, "example": "a1c6a2ab-4b01-4253-b4c9-70e04b3b48fc" } } ], "responses": { "200": { "description": "Returns JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Action" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Asset_Not_Found": { "value": { "message": "Asset not found" } }, "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/asset": { "post": { "operationId": "CreateAsset", "tags": [ "ASSETS" ], "summary": "Create Asset", "description": "Use this endpoint to perform one of the following operations:\n1) Create a new **Asset**\n2) Create a new **Version** of an existing Asset\n3) Create a new **Metadata-only Asset**\n\nOnce the new Asset or Asset Version is created, a new **Object ID** is returned to identify the new Asset / Asset Version.\n\nWhen a new Asset is created, the Asset is considered a metadata-only asset until a corresponding content file is uploaded. The Asset's content file size must be less than or equal to 5GB.\n\nIf content is included, the response includes one or more presigned URLs (`urls`) and an `uploadId` to upload the content file. The upload should be performed using a PUT request with the file content attached as binary data in the request body. If a **Metadata-only Asset** is created (no content), the response instead includes a single presigned `url` and no `uploadId`, since there is no upload to complete yet.\n\n**After creating an asset greater than 100MB, multiple presigned URLs will be returned. You must upload file chunks of 100MB to each one.**\n\n**You must call the /asset/complete endpoint to complete or abort a multi-part file upload, otherwise the file will not be available to Tenovos.**\n\nThe user submitting the request to create an Asset must have the **Upload** Security Role Privilege and be granted access to at least one Security Template to assign to the new Asset.\n\n**Average Response Time:** 1077ms (varies based on metadata)", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object.\nTo create a **new version** instead of new asset, pass an additional property **originalFileId** as part of the JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateRequest" }, "examples": { "Create_a_New_Asset": { "$ref": "#/components/examples/CreateAsset" }, "Create_a_New_Version": { "$ref": "#/components/examples/CreateNewAssetVersion" }, "Create_Asset_with_Multipart_Upload": { "$ref": "#/components/examples/MultipartUpload" } } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-asset-response" }, "examples": { "Metadata-only Asset": { "value": { "filename": "test.jpg", "filetype": "image/jpeg", "objectId": "e3ad745f-7b6a-464b-b007-f872607a0825", "fileId": "9e87fc1f-63ee-4674-9ab3-e4d1559265fc", "originalFileId": "9e87fc1f-63ee-4674-9ab3-e4d1559265fc", "url": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/masters/9e87fc1f-63ee-4674-9ab3-e4d1559265fc/test.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260828T172108Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host&x-amz-meta-objectid=e3ad745f-7b6a-464b-b007-f872607a0825&x-id=PutObject" } }, "Asset with Content": { "value": { "filename": "test.jpg", "filetype": "image/jpeg", "objectId": "c958613c-0f2c-4d84-8554-43bb76ffbff2", "fileId": "49ee3673-d5ea-4c36-bfce-b0eb94395dcb", "originalFileId": "49ee3673-d5ea-4c36-bfce-b0eb94395dcb", "uploadId": "EXAMPLEUPLOADID", "urls": [ { "partNumber": 1, "url": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/masters/49ee3673-d5ea-4c36-bfce-b0eb94395dcb/test.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260828T172305Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host&partNumber=1&uploadId=EXAMPLEUPLOADID&x-id=UploadPart" } ] } } } } } }, "400": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateValidationErrorResponse" }, "examples": { "Missing Filename": { "value": { "status": "error", "message": "INVALID_REQUEST", "details": [ "Failed to extract Filename or MimeType from Asset for Create Asset Object" ] } }, "Missing FileType": { "value": { "status": "error", "message": "INVALID_REQUEST", "details": [ "Failed to extract Filename or MimeType from Asset for Create Asset Object" ] } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Invalid_Original_File_ID": { "value": { "message": "Invalid Response from Create Asset" } }, "Missing_Metadata": { "value": { "message": "Unexpected end of JSON input" } }, "Missing_Metadata_Template_ID": { "value": { "message": "Invalid Asset: Missing Metadata Template ID" } }, "Missing_Security_Template_ID": { "value": { "message": "Invalid Asset: Missing Security Template ID(s)" } } } } } } } }, "patch": { "operationId": "EditAssets", "tags": [ "ASSETS" ], "summary": "Bulk Edit Assets", "description": "Perform metadata edits and/or reassign Security Templates to one or more Assets. Assets are identified by **Object ID**. If multiple Assets are specified, the same metadata and/or security edits will be applied to all Assets in the request.\n\nEach Metadata Attribute is identified by a Metadata Definition ID.\n\nThe user performing the bulk edit must have the **Edit Metadata** permission granted on each Asset being edited.\n\n**Average Response Time:** 605ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object. The object must contain **metadata** and/or **securityTemplateIds** as well as an array of **objectIds**.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBulkEditRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetBulkEditResponse" } } } }, "400": { "description": "Invalid Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Invalid metadataTemplateId | Invalid Request: Missing Bulk Edit Asset Details" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/asset/{id}": { "get": { "operationId": "GetAsset", "tags": [ "ASSETS" ], "summary": "Get Asset", "description": "Retrieve an Asset's details and metadata by specifying an **Object ID** or **File ID** in the request path.\n\nThe user requesting the Asset must have view access to the Asset in order to retrieve the Asset.\n\n**Average Response Time:** 451ms (Get asset by fileId)\n\n**Average Response Time:** 2973ms (Get asset by objectId)", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Asset **Object ID** or **File ID**", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36 } } ], "responses": { "200": { "description": "Returns JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "404": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Asset_Not_Found": { "value": { "message": "Asset not found" } }, "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } }, "patch": { "operationId": "UpdateAsset", "tags": [ "ASSETS" ], "summary": "Update Asset", "description": "Update the metadata attributes and/or the Security Template assignments for an Asset identified by Object ID. The Object ID must be specified in the request path.\n\nThe user submitting the request must have edit access to the Asset.\n\n**Average Response Time:** 1701ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Asset object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetUpdateRequest" }, "examples": { "updateSecurityTemplates": { "summary": "Update Security Template assignments", "value": { "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] } }, "updateMetadata": { "summary": "Update metadata values", "value": { "metadata": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" } ], "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Invalid_Metadata_Provided": { "value": { "status": "error", "message": "Invalid fields for metadata template" } }, "Invalid_Security_Templates_Provided": { "value": { "status": "error", "message": "Invalid security template ID(s)" } } } } } } } } }, "/asset/{id}/content": { "get": { "operationId": "GetAssetContent", "tags": [ "ASSETS" ], "summary": "Get Asset Download Link", "description": "Retrieve a presigned URL to the Asset's source file by Object ID.\n\nThe user requesting the Asset's source file must have download access to the Asset.\n\n**Average Response Time:** 934ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Asset object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The response is a JSON object containing URL to download the content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetContent" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "502": { "description": "Invalid Asset Object ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Internal server error" } } } } } } }, "/asset/{id}/delete": { "post": { "operationId": "DeleteAsset", "tags": [ "ASSETS" ], "summary": "Delete or Restore Asset", "description": "Soft delete or un-delete an Asset. An Asset that has been soft-deleted can be later purged from the recycle bin. A soft-deleted Asset cannot be edited or downloaded.\n\nThe user attempting to soft delete or un-delete an Asset must be granted the **Delete** Security Template permission on the Asset.\n\n**Average Response Time:** 445ms (Soft Delete an Asset)\n**Average Response Time:** 1055ms (Undeleted an Asset)", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Asset Object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The request body is a JSON object. \nUse **delete** action to soft delete the asset and **un-delete** to un-delete the asset.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetDeleteRequest" }, "examples": { "Delete_Asset": { "value": { "action": "delete", "deleteType": "full" } }, "Un-delete_Asset": { "value": { "action": "undelete", "deleteType": "full" } } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteResponse" } } } }, "400": { "description": "Missing secondaryIds id or linkType", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringErrorResponse" }, "example": "Invalid Request: [\"Missing Secondary Object ID or Link Type for Relationship 0\"]" } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Undelete_Asset_that_is_not_Soft-Deleted": { "value": { "message": "Failed to UnDelete Asset" } } } } } }, "500": { "description": "Invalid Asset Object ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Failed to delete Relationship", "detail": "payload.body.map is not a function" } } } }, "502": { "description": "Missing or Invalid action", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Internal server error" } } } } } } }, "/asset/{id}/latest": { "get": { "operationId": "GetLatestVersion", "tags": [ "ASSETS" ], "summary": "Get Asset Latest Version", "description": "Retrieve latest version of an Asset by specifying an **Object ID** in the request path.\n\nThe user requesting the Asset must have view access to the Asset in order to retrieve the Asset.\n\n**Average Response Time:** 265ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Asset Object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returns JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Asset" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Asset_Not_Found": { "value": { "message": "Asset not found" } }, "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/asset/{id}/link": { "get": { "operationId": "GetAssetRelationship", "tags": [ "ASSETS" ], "summary": "Get Asset Relationships", "description": "Retrieve all Asset relationships associated with an Asset specified by Object ID. In a relationship, the Asset can be a primary or secondary (related) Asset. For example, in a parent / derivative relationship, the primary Asset would be the **parent**, while the secondary Asset would be the **derivative**. Both the Object ID and relationship type for each Asset will be returned. Relationships will be retrieved where the Asset is a primary or secondary Asset.\n\nThe user requesting the Asset relationships must have **View** access to both the primary Asset and the secondary Assets in order to retrieve the relationships.\n\n**Average Response Time:** 140ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Asset object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AssetRelationship" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "post": { "operationId": "CreateRelationship", "tags": [ "ASSETS" ], "summary": "Create Asset Relationship", "description": "Create a bidirectional relationship between a primary Asset and one or more secondary Assets. Asset relationships allow a user to quickly navigate from one Asset to another related Asset.\n\nThe user attempting to create a relationship using Asset must be granted the **Relationship** Security Template permission on the Asset.\n\n**Average Response Time:** 3922ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Asset object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body is a JSON object that provides information about relationships to create.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "The response is an array that contains a status(success/failed) for each relationship.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetCreateLinkResponse" } } } }, "400": { "description": "Invalid Asset Object ID or secondaryIds", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringErrorResponse" }, "example": "Failed to create Relationship" } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "patch": { "operationId": "RemoveRelationship", "tags": [ "ASSETS" ], "summary": "Remove Asset Relationship", "description": "Remove a relationship between a primary Asset and one or more secondary Assets. Specify the primary Asset Object ID as a path parameter. Specify the secondary Asset Object IDs and Link Types as an array in the request body.\n\nThe user requesting the Asset relationships must have view access to both the primary Asset and the related Assets in order to relationships and the related Assets.\n\n**Average Response Time:** 929ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Asset object ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelationshipDeleteRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation with relationshipId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetLinkDeleteResponse" } } } }, "400": { "description": "Invalid JSON request object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringErrorResponse" }, "example": "Invalid Request: [\"Missing Secondary Object IDs\"]" } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/asset/{id}/version": { "get": { "operationId": "GetVersions", "tags": [ "ASSETS" ], "summary": "Get Asset Version History", "description": "Retrieve a list of all versions of an Asset by specifying an **Object ID** or Original **File ID** in the request path.\n\nThe user requesting the Asset must have view access to the Asset in order to retrieve the Asset version history.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Object ID or File ID of the asset.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/Asset" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Returns JSON object with error message", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Forbidden": { "value": { "message": "Forbidden" } }, "Invalid_Object_ID": { "value": { "message": "Asset not found" } } } } } } } } }, "/asset/{id}/version/promote": { "post": { "operationId": "PromoteAssetVersion", "tags": [ "ASSETS" ], "summary": "Promote Asset Version", "description": "Promote an existing version of an Asset to be its current version. The Asset is identified by an **Object ID** or **File ID** in the request path; the version to promote is identified by the `fileId` in the request body.\n\nPromoting a version creates a new current version from the nominated one, and carries the Asset's existing collection memberships and relationships onto it.\n\nThe user requesting the promotion must have access to the Asset.\n\n**Note on response shape:** the `data` property carries the newly created asset-version record. Its fields are not enumerated in the handler's type definitions, so they are not documented here — see `GET /asset/{id}` for the Asset shape.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Object ID or File ID of the asset whose version is being promoted.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "fileId" ], "properties": { "fileId": { "type": "string", "description": "File ID of the existing version to promote to current.", "example": "8cd2c221-6a91-4dc6-9379-d55dca9d5313" } } } } }, "required": true }, "responses": { "200": { "description": "Asset version promoted successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Asset version promoted successfully" }, "data": { "type": "object", "description": "The newly created asset-version record. Field-level shape is not declared in the handler's types; see `GET /asset/{id}` for the Asset shape." } } }, "example": { "status": "success", "message": "Asset version promoted successfully" } } } }, "401": { "description": "Unauthorized. Returned when the `Authorization` header is missing or the token is invalid, and also when the user lacks the privilege or permission to act on the Asset — this endpoint returns 401 rather than 403 for an access failure.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Unauthorized": { "value": { "status": "error", "message": "Unauthorized" } }, "No_Privilege": { "value": { "status": "error", "message": "User does not have the privilege to perform action" } }, "No_Permission": { "value": { "status": "error", "message": "User does not have the permission to perform action" } } } } } }, "403": { "description": "Returned for a missing request body or a missing `fileId` — this endpoint returns 403 rather than 400 for both.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Missing_Body": { "value": { "status": "error", "message": "No data provided in the request body" } }, "Missing_File_Id": { "value": { "status": "error", "message": "Invalid Data: Missing File ID" } } } } } } } } }, "/asset/complete": { "post": { "operationId": "FinishUpload", "tags": [ "ASSETS" ], "summary": "Complete Upload", "description": "Complete/Abort multipart upload once all parts are uploaded. **This endpoint must be called after creating asset when the file is sent in chunks of 100MB each. For files 100MB or less in size this operation is not needed.** \n\n**Average Response Time:** 1310ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMultipartUploadRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetMultipartUploadResponse" } } } }, "400": { "description": "Error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Validation_Errors": { "value": { "message": "Failed to parse asset: Missing fields" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/asset/content/preview": { "post": { "operationId": "ReplacePreview", "tags": [ "ASSETS" ], "summary": "Assign Asset Preview Image", "description": "\"Generate a request to upload an image or PDF file to be the new preview for one or more Assets. Supported preview image formats include: GIF, JPG, PNG, and TIFF.\\n\\nIf a PDF file is uploaded to be the preview for a document Asset, then the PDF will also be displayed in the Asset Detail page as the multi-page PDF preview.\\n\\nAfter submitting the request to replace an Asset preview, \\n\\nThe user replacing the Asset previews must be granted the **Replace Mezzanine** and **Upload** User Role Permissions and **View** Security Template Permission on the Assets being updated.\\n\\nFor Federated Assets, if user provides optional **contentPaths** key in the request body, then files referenced in the **contentPaths** > **** properties are used as renditions.\"\n\n**Average Response Time:** 953ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetReplacePreviewRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetReplacePreviewResponse" }, "example": [ { "filename": "Preview.jpg", "fileId": "b3b43fe0-17aa-4e0e-bbe3-b80c915f5508", "url": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/preview/b3b43fe0-17aa-4e0e-bbe3-b80c915f5508/Preview.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260619%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260619T190544Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host" } ] } } }, "400": { "description": "Invalid status value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StringErrorResponse" }, "examples": { "Missing_Asset_File_ID": { "value": "The following fields are required, but are missing or incorrect [\"fileIds\"]" }, "Missing_File_Name": { "value": "The following fields are required, but are missing or incorrect [\"filename\"]" }, "Missing_File_Size": { "value": "The following fields are required, but are missing or incorrect [\"filesize\"]" }, "Invalid_File_ID": { "value": "Provided fileIds are invalid" }, "Invalid_Rendition_Type_in_Content_Paths": { "value": "Invalid Rendition Name(s): invalidName" }, "File_Referenced_in_Content_Paths_Not_Found": { "value": "File not found on provided content path" }, "No_Rendition_Path_Specified_in_Content_Paths": { "value": "No Rendition Path Specified" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/asset/{id}/history": { "get": { "operationId": "getAssetHistory", "tags": [ "ASSETS" ], "summary": "Asset History", "description": "This endpoint returns a complete history of all events", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/id" }, { "$ref": "#/components/parameters/userId" }, { "$ref": "#/components/parameters/eventType" }, { "$ref": "#/components/parameters/startDate" }, { "$ref": "#/components/parameters/endDate" }, { "$ref": "#/components/parameters/limit" }, { "$ref": "#/components/parameters/cursor" } ], "responses": { "200": { "description": "Successful Request. Event Types Retrieved Successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/event-history" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/asset/expose": { "post": { "operationId": "GetAssetUrl", "tags": [ "ASSETS" ], "summary": "Generate Temporary Asset Preview Link", "description": "Exposes Asset's pre-signed urls with expiration time given in seconds\n\nAsset being exposed needs to have a Security Template with **Download** permission and User must have a role with the **Download** privilege.\n\n**Average Response Time:** 785ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON array.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetExposeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetExposeResponse" } } } }, "400": { "description": "Error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "No_Asset_Found": { "value": { "message": "No assets found" } }, "Validation_Errors": { "value": { "message": "Body requires at least single item" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or expired token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/asset/scan": { "post": { "operationId": "ScanAssets", "tags": [ "SEARCH" ], "summary": "Scan Asset Search Results", "description": "Provides the ability to scan a search result set of assets using a cursor to fetch the next set of results pages on the limit (page size) passed.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Scan" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object\n \n ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "example": { "status": "error", "message": "Invalid Search Query" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Failed operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/asset/share": { "post": { "operationId": "ShareAssets", "tags": [ "ASSETS" ], "summary": "Share a selection of Assets.", "description": "Share a selection of Assets to a user specified by Email address.\n\nThe user sharing the Assets must be granted the **Download** Security Template permission on the Assets being shared.\n\n**Average Response Time:** 195ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body is a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetShareRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetShareResponse" }, "examples": { "Success": { "value": { "message": "", "collectionId": "56fab5f7-066a-4db8-aec2-9b9adcc75220", "statusCode": "success", "collectionUrl": "https://pa.app.tenovos.io/#/collection/56fab5f7-066a-4db8-aec2-9b9adcc75220", "status": "success" } }, "Missing_Recipient": { "value": { "message": "Bad Data. Recipient information is required." } }, "Invalid_Asset_File_ID": { "value": { "status": "error", "message": "Either the users or assets does not belong to senders customer" } }, "Missing_Asset_File_ID": { "value": { "status": "error", "message": "Invalid input. No Collection or Assets are selected to share." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Invalid Share Asset: Missing shareUsers" } } } } }, "examples": { "Missing_Sender": { "value": { "message": { "statusCode": 400, "message": "Missing Sender" } } }, "Missing_Share_Users": { "value": { "message": { "statusCode": 400, "message": "Invalid Share Asset: Missing shareUsers" } } }, "Invalid_Share_Users": { "value": { "message": { "statusCode": 400, "message": "Either the users or assets does not belong to senders customer" } } } } } } } } } }, "/asset/transform": { "post": { "operationId": "GetTransformation", "tags": [ "ASSETS" ], "summary": "Share or Download Asset Transformation", "description": "Transform asset and download or share transformation with an email. If email is available then this API will share link (send email) of transformed file.\n\nNote: Access to this API Service is currently limited. Contact Tenovos Customer Support to inquire further about access to this API Service if needed.\n\n**Average Response Time:** 937ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "X-API-Verification-Key", "in": "header", "description": "Additional Customer-specific API verification key to limit access to this API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body is a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetTransformRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssetTransformResponse" }, "examples": { "Success": { "value": { "message": "Message sent successfully" } }, "Missing_Recipient": { "value": { "message": "Bad Data. Recipient information is required." } }, "Invalid_Asset_File_ID": { "value": { "status": "error", "message": "Either the users or assets does not belong to senders customer" } }, "Missing_Asset_File_ID": { "value": { "status": "error", "message": "Invalid input. No Collection or Assets are selected to share." } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "Missing_Sender": { "value": { "message": "Missing Value for Sender" } }, "Missing_Share_Users": { "value": { "message": "Invalid Share Asset: Missing shareUsers" } }, "Invalid_Share_Users": { "value": { "status": "error", "message": "Either the users or assets does not belong to senders customer" } } } } } } } } }, "/assets/asset": { "post": { "operationId": "create-asset-v1.5", "tags": [ "ASSETS" ], "summary": "Create an Asset", "description": "Use this endpoint to perform one of the following:\n - Create a new Asset\n - Create a new version of an existing Asset\n - Create a new Metadata-only Asset\n\nOnce the new Asset or version is created, a new object ID is returned in the response to identify the new Asset / Asset Version.\nWhen a new Asset is created, the Asset is considered a metadata-only Asset until a corresponding content file is uploaded. The Asset's content file size must be less than or equal to 5GB.\n\nAfter invoking the Create Asset endpoint, the response will include a signed URL to upload the content file. The upload should be performed using a PUT request with the file content attached as binary data in the request body.\n\nAfter creating an asset greater than 100MB, multiple presigned urls will be returned. You must upload file chunks of 100MB to each one.\n\nYou must call the /asset/complete endpoint to complete or abort a multi-part file upload, otherwise the file will not be available to Tenovos.\n\n**The user submitting the request to create an Asset must have the Upload Security Role Privilege and be granted access to at least one Security Template to assign to the new Asset.**", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.\nTo create a **new version** instead of new asset, pass an additional property **originalFileId** as part of the JSON object.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/create-asset" }, { "$ref": "#/components/schemas/create-asset-version" }, { "$ref": "#/components/schemas/create-multipart-asset" } ] }, "examples": { "createAsset": { "summary": "Create a new Asset", "value": { "filename": "hooli-logo.jpg", "objectType": "Asset", "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "securityTemplateIds": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "metadata": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" } ] } }, "createAssetVersion": { "summary": "Create a new version of an existing Asset", "value": { "originalFileId": "33df0bfb-2465-427b-ae8c-4476e7f6e112", "filename": "hooli-logo.jpg", "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "securityTemplateIds": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "metadata": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" } ] } }, "createMultipartAsset": { "summary": "Create a large Asset (multipart upload)", "value": { "filename": "hooli-logo.jpg", "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "securityTemplateIds": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "filesize": 9019431322, "metadata": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-asset-response-legacy" }, "examples": { "Metadata-only Asset": { "value": { "status": "success", "message": "Asset created successfully", "data": { "objectId": "6c3bc79a-c9b3-426b-9eb1-931a7f6be22c", "filename": "test.jpg", "fileId": "cd5bffd1-f7bf-4aee-a46c-12f351931071", "originalFileId": "cd5bffd1-f7bf-4aee-a46c-12f351931071", "url": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/masters/cd5bffd1-f7bf-4aee-a46c-12f351931071/test.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260828T172622Z&X-Amz-Expires=84600&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host&x-amz-acl=bucket-owner-full-control&x-amz-meta-objectid=6c3bc79a-c9b3-426b-9eb1-931a7f6be22c&x-id=PutObject" } } }, "Asset with Content": { "value": { "status": "success", "message": "Asset created successfully", "data": { "objectId": "68504beb-e861-45af-93b0-f422a119a28c", "filename": "test.jpg", "fileId": "0d549801-c6de-42f9-9100-f195ce38ce1f", "originalFileId": "0d549801-c6de-42f9-9100-f195ce38ce1f", "uploadId": "EXAMPLEUPLOADID", "urls": [ { "partNumber": 1, "url": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/masters/0d549801-c6de-42f9-9100-f195ce38ce1f/test.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260828T172652Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host&partNumber=1&uploadId=EXAMPLEUPLOADID&x-id=UploadPart" } ] } } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired. Also occurs if the user does not have the permission to perform the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key or Invalid Metadata Template", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/assets/asset/{id}": { "get": { "operationId": "get-asset-v1.5", "tags": [ "ASSETS" ], "summary": "Retrieve an Asset", "description": "Retrieves an asset's details and metadata by specifying an Asset Identifier or File Identifier in the request path.\n\n** The user requesting the Asset must have view access to the Asset. **", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The Asset Identifier (same as objectId) to retrieve.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid" } }, { "name": "empty", "in": "query", "description": "Default is `true`. When false, results will not include metadata without values, when true all metadata attributes for the asset will be returned even those with no values provided.", "required": false, "schema": { "type": "boolean" } }, { "name": "system", "in": "query", "description": "Default is `true`. When false, system metadata fields will be excluded from the metadata array that is returned in the response.", "required": false, "style": "simple", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-asset-response" }, "example": { "status": "success", "message": "success", "data": { "createdDate": "2026-04-30T12:10:06.344Z", "lastUpdatedDate": "2026-04-30T21:00:54.901Z", "fileId": "8006d135-eed6-4b9a-8032-8eb16ee4d220", "filename": "hooli-logo.jpg", "originalFileId": "8006d135-eed6-4b9a-8032-8eb16ee4d220", "createdBy": { "id": "7d675ef0-f423-11e9-8071-89c0c4052141", "firstName": "Erlich", "lastName": "Bachman", "email": "erlich.bachman@piedpiper.com" }, "lastUpdatedBy": { "id": "4b5896b4-33e4-41ac-b251-39a4dbaa25b2", "firstName": "Richard", "lastName": "Hendricks", "email": "richard.hendricks@piedpiper.com" }, "assetId": "2ae604c3-e102-4ecf-a395-6c6e4cbb87a4", "type": "Asset", "currentVersion": true, "versionNumber": 1777551006344, "AITags": [], "metadataState": "available", "metadataTemplateId": "4604b6b3-59f5-4fa1-855d-4db6726dbe66", "renditionsDocument": { "width": 5155, "height": 3437, "imageThumb": "https://url.content.tenovos.io/1739271540099/8006d135-eed6-4b9a-8032-8eb16ee4d220/38da751e-e298-4974-9b08-ec745090a4cf-200x200.png", "imagePreview": "https://url.content.tenovos.io/1739271540099/8006d135-eed6-4b9a-8032-8eb16ee4d220/38da751e-e298-4974-9b08-ec745090a4cf-700x700.png", "mezzaninePreview": "https://url.content.tenovos.io/1739271540099/8006d135-eed6-4b9a-8032-8eb16ee4d220/38da751e-e298-4974-9b08-ec745090a4cf-3000x3000.png", "imagePreviewLarge": "https://url.content.tenovos.io/1739271540099/8006d135-eed6-4b9a-8032-8eb16ee4d220/38da751e-e298-4974-9b08-ec745090a4cf-1000x1000.png" }, "fileState": "available", "securityTemplateIds": [ "8d143556-fa75-45f7-9cef-4f11a2940bb0", "7803c6cf-5e00-4733-9b0b-cdd6f5ef1ddd" ], "lockType": [], "avamTags": [], "metadata": [ { "id": "f62a7aa1-7a6b-4280-8070-a206d3afeb0a", "name": "Asset Type", "value": "Lifestyle Photo" }, { "id": "b18541d1-256f-4780-b84f-b11ef781ee4a", "name": "Product Category", "value": [ "Shoes" ] }, { "id": "6a8101e4-6d72-4078-b2cd-693ff1cf59a1", "name": "System Content Type", "value": "Image" }, { "id": "218e78aa-37fb-4f31-b473-d8bd860eb55d", "name": "System Created Date", "value": 1777551006344 }, { "id": "a84ea108-169f-482c-98b9-f42dac2fadbf", "name": "System Created By", "value": "Erlich Bachman (erlich.bachman@piedpiper.com)" }, { "id": "5403784e-0b1e-412e-aefd-48fa97027fa3", "name": "System Last Updated By", "value": "Richard Hendricks (richard.hendricks@piedpiper.com)" } ], "fileSizeInBytes": 209743 } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired. Also occurs if the user does not have the permission to perform the action.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key or Asset Not Found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "status": { "type": "string" } } }, "example": { "message": "Asset not found", "status": "error" } } } } } }, "patch": { "operationId": "update-asset-v1.5", "tags": [ "ASSETS" ], "summary": "Update an Asset", "description": "Update the metadata attribute values and/or the Security Template assignments for an Asset identified by Object ID (Asset ID). ** The identifier must be specified in the path parameter.\n\n** The user requesting the Asset must have edit role privilege, as well as edit permission on the Asset's security template in order to update the Asset. **", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The Asset Identifier belonging to the Asset to update.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "description": "The Request Body must be a JSON object.\nUpdate the security templates assigned to an Asset, or update metadata values. Only those values you wish to change need to be provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-asset" }, "examples": { "updateSecurityTemplates": { "summary": "Update Security Template assignments", "value": { "securityTemplateIds": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] } }, "updateMetadata": { "summary": "Update metadata values", "value": { "securityTemplateIds": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "metadata": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" } ] } } } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-response" }, "example": { "status": "success", "message": "Asset update was successful" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired. Also occurs if the user does not have the permission to perform the action.\n\n**Note:** This status code is also returned when a provided metadata value fails validation (for example, an invalid controlled vocabulary value), rather than a 400.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Unauthorized": { "value": { "status": "error", "message": "Unauthorized" } }, "Invalid_Metadata_Value": { "value": { "status": "error", "message": "[\"Invalid value [2029] provided for the attribute [Year]\"]" } } } } } }, "403": { "description": "Forbidden. Missing X-API-key or Asset Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Missing_X-API-key": { "value": { "status": "error", "message": "Forbidden" } }, "Asset_Not_Found": { "value": { "status": "error", "message": "Asset not found" } } } } } } } } }, "/workflow-templates": { "get": { "operationId": "GetProofTemplate", "tags": [ "PROOFING" ], "summary": "Get Workflow Templates", "description": "Get active workflow templates.\n\n**Average Response Time:** 9690ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkflowTemplateResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/proof/{id}/status": { "get": { "operationId": "GetProofStatus", "tags": [ "PROOFING" ], "summary": "Get Proof Status", "description": "Get Proof status and decision status", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a Proof ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofStatusResponse" } } } }, "400": { "description": "Error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/proofing/user": { "post": { "operationId": "CreateProofUser", "tags": [ "PROOFING" ], "summary": "Create a Proofing User", "description": "Creates a Proofing User account. Must be a Story Orchestration customer and have available user licenses.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProofUser" } } }, "required": true }, "responses": { "200": { "description": "Successful Operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProofUserResponse" } } } }, "400": { "description": "Error occurred", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/proof/{id}/reviewer-url": { "post": { "operationId": "GetReviewerUrl", "tags": [ "PROOFING" ], "summary": "Get Reviewer URL", "description": "Get proof Reviewer URL.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "X-API-Verification-Key", "in": "header", "description": "Verification key created in Config customer specific.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a Proof ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body is a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProofReviewerUrlRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetProofReviewerUrlResponse" }, "example": { "url": "https://myco.com/proof/mumcj6m7l07s07sh7smo70sn93" } } } }, "400": { "description": "Invalid email is Inputted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Email": { "value": { "message": "Please provide valid email" } }, "Invalid_Proof_ID": { "value": { "message": "‘Valid Proof ID is Required’" } }, "Missing_X-API-Verification-Key": { "value": { "message": "X-API-Verification-Key header is missing" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Unauthorized": { "value": { "message": "Unauthorized" } } } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/auth/token": { "post": { "security": [ { "BasicAuth": [], "ApiKeyAuth": [] } ], "operationId": "GetAuthToken", "tags": [ "AUTHENTICATION" ], "summary": "Authorize Session", "description": "Generates authentication credentials that expire after one hour.\n\nThe authentication response includes an **accessToken** which is used as the AccessToken request header when performing any authenticated operation.\n\nThis operation will also accept the previous authentication response as the request payload to return a refreshed access token. The access token expires after 1 hour and must be refreshed after expiration, using the included **refreshToken**. The refresh token can be used for up to 30 days to request new access tokens, or until the refresh token is revoked. Once the refresh token expires or is revoked, the user credentials must be provided again to generate a new access token and refresh token.\n\n**Average Response Time:** 3671ms (New Token)\n\n**Average Response Time:** 233ms (Refresh Token)", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON-formatted string.\n\nThe following parameters are required to request an access token:\n* username\n* password\n\nThe following parameters are required to refresh the access token:\n* accessToken\n* refreshToken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRequest" }, "examples": { "New_Token": { "$ref": "#/components/examples/newTokenExample" }, "Refresh_Token": { "$ref": "#/components/examples/refreshTokenExample" } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } }, "401": { "description": "Unauthorized operation. This occurs when invalid user credentials are provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "No_Client_ID": { "value": { "status": "error", "message": "2 validation errors detected: Value '' at 'clientId' failed to satisfy constraint: Member must have length greater than or equal to 1; Value '' at 'clientId' failed to satisfy constraint: Member must satisfy regular expression pattern: [\\w+]+" } }, "No_Username": { "value": { "status": "error", "message": "Invalid Authentication Parameters" } }, "No_Password": { "value": { "status": "error", "message": "Missing required parameter PASSWORD" } } } } } } } }, "delete": { "operationId": "ExpireToken", "tags": [ "AUTHENTICATION" ], "summary": "Expire Access Token", "description": "Expire an access token before the token's expiration date and revoke access to the system. \n\n***Access tokens normally expire within an hour.***\n\nThis operation expires an access token upon request so that the token may no longer be used for future operations.\n\n**Average Response Time:** 288ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "AccessToken", "in": "header", "description": "JWT token provided by Authentication Token creation operation. This header is required specifically for the Expire Token API to identify which token to expire.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON-formatted string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthExpireRequest" }, "examples": { "Expire_Token": { "$ref": "#/components/examples/expireTokenExample" } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthExpireResponse" } } } }, "401": { "description": "Unauthorized operation. This occurs when invalid refresh token and user credentials are provided.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Failed to Expire Session and Logout 1" } } } }, "502": { "description": "Bad Gateway. Missing clientId or userPoolId", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Internal server error" } } } } } } }, "/auth/impersonate": { "post": { "operationId": "Impersonate", "deprecated": true, "tags": [ "AUTHENTICATION" ], "summary": "Impersonate User", "description": "This endpoint generates an Access Token and Authorization given a system username.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON-formatted string.\n\nThe following parameters are required to request an access token:\n* username\n\n* The credentials obtained after invoking this API will not be able to refresh tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateRequest" }, "examples": { "New_Session": { "$ref": "#/components/examples/impersonateUserExample" } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "No_Username": { "value": { "status": "error", "message": "Invalid Authentication Parameters" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } }, "422": { "description": "Pre Conditions Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters", "/auth/impersonate": { "post": { "operationId": "Impersonate", "tags": [ "AUTHENTICATION" ], "summary": "Impersonate User", "description": "This endpoint ", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON-formatted string.\n\nThe following parameters are required to request an access token:\n* username\n\n* The credentials obtained after invoking this API will not be able to refresh tokens", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateRequest" }, "examples": { "New_Session": { "$ref": "#/components/examples/impersonateUserExample" } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImpersonateResponse" } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "No_Username": { "value": { "status": "error", "message": "Invalid Authentication Parameters" } } } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } }, "422": { "description": "Pre Conditions Failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "status": "error", "message": "Invalid Authentication Parameters" } } } } } } } } } } } } } }, "/collection": { "post": { "operationId": "CreateCollection", "tags": [ "COLLECTIONS" ], "summary": "Create Collection", "description": "Create a collection and add assets to it. Assets in the collection are identified by FileID therefore **collectionDocument** contains **File ID**\n\nThe user should have **View** permission on assets to be added to the collection.\n\n**Average Response Time:** 200ms (Private Collection)\n\n**Average Response Time:** 2568ms (Shared Collection)", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object. ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateRequest" }, "examples": { "Create_a_Collection": { "$ref": "#/components/examples/CreateCollection" } } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionCreateResponse" }, "examples": { "Success": { "$ref": "#/components/examples/CollectionCreateSuccessResponse" }, "Missing_Required_Fields": { "$ref": "#/components/examples/CollectionCreateErrorResponse" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_Collection_ID": { "value": { "message": "Collection does not exist" } } } } } }, "409": { "description": "Conflict — a collection with the same name and customerId already exists, or some of the provided assets do not belong to the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "status": "error", "message": "A collection with the same name and customerId already exists or some assets do not belong to the customer" } } } } } } }, "/collection/{id}": { "get": { "operationId": "GetCollection", "tags": [ "COLLECTIONS" ], "summary": "Get Collection", "description": "Retrieve a single Collection specified by Collection ID. The retrieved Collection may be either a secured Collection or a private Collection created by the User. The Collection will include the list of Assets assigned to the Collection, referenced by Asset **File ID**.\n\nThe User retrieving the Collection must have the **Collection** Security Role Privilege.\n\n**Average Response Time:** 53ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify Collection ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object describing the collection.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Collection" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "response contains detailed error message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Does Not Exist": { "value": { "message": "Collection does not exist" } }, "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } }, "delete": { "operationId": "DeleteCollection", "tags": [ "COLLECTIONS" ], "summary": "Delete Collection", "description": "User can delete the collection, but the Assets assigned to the Collection will remain and dissociate from this Collection.\n\nThe User submitting the request to delete a private Collection must have the **Collection** and **Delete** Security Role Privilege. Secured Collections may only be deleted by Users with the **Purge** Security Role Privilege.\n\n**Note:** If the specified Collection ID does not exist, this endpoint returns HTTP 200 with `status: error` in the response body, rather than a 4xx error status. This differs from GetCollection and UpdateCollection, which return an error status code (403) when the Collection ID does not exist.\n\n**Average Response Time:** 81ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify Collection ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Returned both when the Collection is successfully deleted and when the specified Collection ID does not exist. Check the `status` field to distinguish between the two cases.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionDeleteResponse" }, "examples": { "Success": { "value": { "status": "success", "message": "Collection delete operation succeeded", "collectionId": "aaee01be-8ba4-49a7-8411-c5f3f4a84f45" } }, "Does Not Exist": { "value": { "status": "error", "message": "Collection does not exist", "collectionId": "aaee01be-8ba4-49a7-8411-c5f3f4a84f45" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "patch": { "operationId": "UpdateCollection", "tags": [ "COLLECTIONS" ], "summary": "Update Collection", "description": "Update a Collection's attributes or assigned Assets. The list of existing assets is replaced with assets provided in the call. Assets in the collection are referenced by Asset **FileID** therefore the **collectionDocument** must contain asset's **FileID**.\n\nThe User editing the Collection must have the **Collection** Security Role Privilege. The User must have **View** access to the Assets that are being added to or removed from the Collection.\n\n**Average Response Time:** 5070ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify Collection ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "type": "array", "example": { "message": "Collection update was successful" }, "items": { "$ref": "#/components/schemas/CollectionUpdateResponse" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_Collection_ID": { "value": { "message": "A collection with the same name and customerId already exists" } } } } } } } } }, "/collections/{id}": { "patch": { "operationId": "UpdateCollectionNew", "tags": [ "COLLECTIONS" ], "summary": "(NEW!) Update Collection", "description": "Update a collection's name, assets, metadata, and/or security templates in a single request. All fields are optional — only provided fields are applied, and omitted fields remain unchanged.\n\n**Asset Updates (`collectionUpdates`):**\n- `add` — appends the provided `fileIds` to the existing asset set.\n- `remove` — removes the provided `fileIds` from the existing asset set.\n- `replace` — replaces the entire asset set with the provided `fileIds`.\n\n**Metadata Updates (`metadata`):**\n- Partial-update semantics: only the attributes included in the array are changed. Attributes not listed remain untouched.\n- `metadata.value` supports both standard attribute values and table-type values. \n\n**Security Templates (`securityTemplateIds`):**\n- When provided, replaces the collection's existing security template assignments entirely.\n- When omitted, existing security template assignments remain unchanged.\n\nThe User submitting the request must have permission to edit the Collection. The User must have **View** access to any Assets being added to or removed from the Collection.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the collection to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e8b8e00f-83ba-49e3-894b-823e5e5bfa2d" } } ], "requestBody": { "description": "JSON object with fields to update. All fields are optional — only provided fields are applied.\nAt least one of `collectionName`, `collectionUpdates`, `metadata`, or `securityTemplateIds` must be present.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "collectionName": { "type": "string", "description": "New display name for the collection.", "example": "Hooli Assets" }, "securityTemplateIds": { "type": "array", "description": "Replaces existing security template assignments. Omit to leave current assignments unchanged.", "items": { "type": "string", "format": "uuid" }, "example": [ "ccf72d28-87a2-4ff4-b5a7-1e54a1155a2a", "e13fc6d5-7ad9-453f-9bca-614e691ef74e" ] }, "collectionUpdates": { "type": "object", "description": "Defines an operation to add, remove, or replace assets in the collection. Accepts a list of fileIDs.", "required": [ "operation", "fileIds" ], "properties": { "operation": { "type": "string", "description": "The operation to perform on the collection's asset set.", "enum": [ "add", "remove", "replace" ], "example": "add" }, "fileIds": { "type": "array", "description": "Asset file IDs to apply the operation against.", "items": { "type": "string", "format": "uuid" }, "example": [ "4a92ca5e-6c62-4bea-b3d2-e7f3bac7c399", "508c0b31-f698-412d-8c4e-4ff39ac12410" ] } } }, "metadata": { "type": "array", "description": "Metadata key/value pairs to update. Only listed attributes are changed — others remain untouched.", "items": { "type": "object", "required": [ "name", "value" ], "properties": { "name": { "type": "string", "description": "The metadata attribute name.", "example": "Department" }, "value": { "description": "The attribute value. Supports standard attribute values (string, date) and table-type values.", "example": "Marketing" } } } } } }, "examples": { "Add Assets And Update Metadata": { "summary": "Add assets and update a metadata field", "value": { "collectionName": "Hooli Assets", "securityTemplateIds": [ "ccf72d28-87a2-4ff4-b5a7-1e54a1155a2a", "e13fc6d5-7ad9-453f-9bca-614e691ef74e" ], "collectionUpdates": { "operation": "add", "fileIds": [ "4a92ca5e-6c62-4bea-b3d2-e7f3bac7c399", "508c0b31-f698-412d-8c4e-4ff39ac12410" ] }, "metadata": [ { "name": "Department", "value": "Marketing" } ] } }, "Replace All Assets": { "summary": "Replace entire asset set", "value": { "collectionUpdates": { "operation": "replace", "fileIds": [ "4a92ca5e-6c62-4bea-b3d2-e7f3bac7c399" ] } } }, "Update Security Templates Only": { "summary": "Swap security template assignments without touching assets or metadata", "value": { "securityTemplateIds": [ "ccf72d28-87a2-4ff4-b5a7-1e54a1155a2a", "e13fc6d5-7ad9-453f-9bca-614e691ef74e" ] } } } } } }, "responses": { "200": { "description": "Collection updated successfully.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "collectionId": { "type": "string", "format": "uuid" } } }, "examples": { "Update Successful": { "summary": "All updates applied successfully", "value": { "status": "success", "message": "Collection update was successful", "collectionId": "e8b8e00f-83ba-49e3-894b-823e5e5bfa2d" } } } } } }, "206": { "description": "Partial success — the request was processed but some assets were already present in the collection (for `add` operations) or not present (for `remove` operations). The response indicates how many assets were affected and how many were skipped.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "collectionId": { "type": "string", "format": "uuid" } } }, "examples": { "Partial Add": { "summary": "Some assets already existed in the collection", "value": { "status": "partial", "message": "2 assets were successfully added. 1 asset already exists in the selected collection.", "collectionId": "e8b8e00f-83ba-49e3-894b-823e5e5bfa2d" } } } } } }, "400": { "description": "Bad request — invalid collection ID or unrecognized field in the request payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Collection_Id": { "value": { "message": "Invalid collection id", "status": "error" } }, "Invalid_Field": { "value": { "message": "Invalid field(s): collectioName", "status": "error" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Collection Security Role Privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no collection exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Collection not found" } } } } } } }, "/collection/{id}/share": { "post": { "operationId": "ShareCollection", "tags": [ "COLLECTIONS" ], "summary": "Share Collection Contents", "description": "Share the zip file of all accessible Assets in a collection and send to the specified emails in share users list. User can also send the custom share message along with request. \\n\\nThe user sharing the Assets must be granted the **Download** and **Share** Security Template permission on the Assets being shared.\n\n**Average Response Time:** 49ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify Collection ID", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionShareRequest" } } }, "required": true }, "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionShareResponse" } } } }, "400": { "description": "Invalid status value" }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_Collect_ID": { "value": { "message": "Collection does not exist" } } } } } } } } }, "/cdn/pullzone/{pullZoneId}": { "get": { "operationId": "getPullZone", "tags": [ "CDN (Coming Soon!)" ], "summary": "Get Pull Zone", "description": "**COMING SOON!**\n\nThis endpoint returns all available about a customer configured CDN Pull Zone, including monthly bandwidth usage. ", "parameters": [ { "$ref": "#/components/parameters/pull-zone-id" }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "responses": { "200": { "description": "Successful Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pull-zone" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/cdn/pullzone": { "post": { "operationId": "createPullZone", "tags": [ "CDN (Coming Soon!)" ], "summary": "Create Pull Zone", "x-status": "coming-soon", "description": "Configure Tenovos CDN Pull Zone. CDN Pull Zones should be based in a region closest to where your content needs to be served to ensure the lowest latency possible. Consider geo-replication for serving content to global users.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object of the available configuration properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pull-zone" } } } }, "responses": { "200": { "description": "Successful Request. CDN Zone Successfully Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pull-zone" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } }, "patch": { "operationId": "editPullZone", "tags": [ "CDN (Coming Soon!)" ], "summary": "Update Pull Zone", "description": "Update your Tenovos CDN Pull Zone Configuration. CDN Zones should be based on a region closest to where your content needs to be delivered to ensure the lowest latency possible. Consider geo-replication for global delivery.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object of the available configuration properties.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/pull-zone" } } } }, "responses": { "204": { "description": "The CDN zone was successfully updated" }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/cdn/pullzone/stats/{pullZoneId}": { "get": { "operationId": "pullZoneStats", "tags": [ "CDN (Coming Soon!)" ], "summary": "Pull Zone Statistics", "x-status": "coming-soon", "description": "Use this endpoint to retrieve usage statistic for a specified Pull Zone.", "parameters": [ { "$ref": "#/components/parameters/pull-zone-id" }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "responses": { "200": { "description": "Successful Request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cdn-pullzone-stats" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/metadata/attributes": { "get": { "operationId": "getMetadataAttributes", "tags": [ "METADATA ATTRIBUTES" ], "summary": "Metadata Attributes", "description": "Retrieve all metadata attributes available to the requesting user.\n\nThe user submitting the request must have administrator privilege to Metadata Management.\n\n**Defaults:**\n- `sort` defaults to `metadataDefinitionName`.\n- `order` defaults to `asc`.\n- `filterFor` is unset by default, applying no filter.\n\n**Business Rules:**\n- `filterFor` narrows the response to attributes usable with a specific set of template types — `listView` covers `default` and `asset` templates, `filterPresets` covers `default`, `asset` and `rights`, and `requestInbox` covers `action`.\n- `order` is matched **case-sensitively**. Only lowercase `asc` and `desc` are accepted; `ASC` is rejected.\n- An invalid `filterFor`, `sort`, or `order` is rejected with a **403**, not the `400` returned by the other list endpoints in this API. Values are validated in the order `filterFor`, `sort`, `order`, so the first invalid one determines the message.\n\n**Average Response Time:** 492ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "filterFor", "in": "query", "description": "Narrows the response to attributes usable with a specific set of template types. `listView` covers `default` and `asset` templates, `filterPresets` covers `default`, `asset` and `rights`, and `requestInbox` covers `action`. Omitted applies no filter.", "required": false, "schema": { "type": "string", "enum": [ "listView", "filterPresets", "requestInbox" ] }, "example": "listView" }, { "name": "sort", "in": "query", "description": "Field to sort results by. Defaults to `metadataDefinitionName`.", "required": false, "schema": { "type": "string", "enum": [ "metadataDefinitionName", "metadataDefinitionSearchField" ], "default": "metadataDefinitionName" } }, { "name": "order", "in": "query", "description": "Sort direction. Matched case-sensitively — only lowercase values are accepted. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "The Response Body will be a JSON array of template objects.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-attributes" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Returned for a missing X-API-key, and also for an invalid `filterFor`, `sort`, or `order` — this endpoint rejects bad query parameters with a `403` rather than the `400` used elsewhere in this API.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Forbidden": { "value": { "message": "Forbidden" } }, "Invalid_Filter_For": { "value": { "message": "Invalid [filterFor] [listview] provided. Supported values are [listView, filterPresets, requestInbox]" } }, "Invalid_Sort": { "value": { "message": "Invalid [sort] [name] provided. Supported values are [metadataDefinitionName, metadataDefinitionSearchField]" } }, "Invalid_Order": { "value": { "message": "Invalid [order] [ASC] provided. Supported values are [asc, desc]" } } } } } } } } }, "/attributes": { "get": { "operationId": "ListMetadataAttributes", "tags": [ "METADATA ATTRIBUTES" ], "summary": "(NEW!) List Metadata Attributes (Paginated)", "description": "Retrieve a paginated list of metadata attributes for UI consumption. Supports filtering by name, type, and usage, pagination via offset, and sorting via query parameters.\n\nThis endpoint replaces the unpaginated `GET /metadata/attributes` for customers with large attribute libraries.\n\n**Defaults:**\n- `attributeType`, `inUse`, and `filterFor` are unset by default, applying no filter.\n\n**Business Rules:**\n- `attributeType` accepts one or more of `textbox`, `textarea`, `date`, `dropdown` as a comma-separated list.\n- `inUse` accepts a boolean (`true`/`false` — aggregate: used anywhere at all) or one of `metadataCascades`, `metadataTables`, `metadataGroups`, `metadataTemplates`, `presets`, filtering to attributes referenced in that specific usage category.\n- `filterFor` filters to attributes usable in a specific consumer context. Currently supports `requestInbox`, which returns only attributes that can be set as Request Inbox columns.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Partial, case-insensitive match against attribute name. When omitted or when `*` is passed, all attributes are returned (subject to pagination).", "required": false, "schema": { "type": "string", "example": "title" } }, { "name": "attributeType", "in": "query", "description": "Comma-separated list of attribute types to filter by. One or more of `textbox`, `textarea`, `date`, `dropdown`. Omitted returns attributes of any type.", "required": false, "schema": { "type": "string", "example": "textbox,textarea,date" } }, { "name": "inUse", "in": "query", "description": "Filters by usage status. `true`/`false` filters on aggregate usage (referenced anywhere at all). One of `metadataCascades`, `metadataTables`, `metadataGroups`, `metadataTemplates`, `presets` filters to attributes referenced in that specific usage category. Omitted applies no filter.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "metadataCascades", "metadataTables", "metadataGroups", "metadataTemplates", "presets" ], "example": "true" } }, { "name": "filterFor", "in": "query", "description": "Filters to attributes usable in a specific consumer context. Currently supports `requestInbox`, which returns only attributes that can be set as Request Inbox columns.", "required": false, "schema": { "type": "string", "enum": [ "requestInbox" ] } }, { "name": "from", "in": "query", "description": "Search offset from which results will start. Defaults to 0.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return. Defaults to 100. Maximum 100.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort by. Defaults to `attributeName`.", "required": false, "schema": { "type": "string", "enum": [ "attributeName", "createdEpoch", "lastUpdatedEpoch", "attributeType", "inUse" ], "default": "attributeName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Paginated list of metadata attributes. Each item in the `results` array is a summary object with the same shape regardless of `attributeType`. Type-specific fields (e.g. `maxCharacterLength`, `vocabularyId`) are only returned by the `GET /metadata/attribute/{id}` detail endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-attribute-list" }, "examples": { "Mixed_Attribute_List": { "summary": "List containing all attribute types", "value": { "hitCount": 4, "results": [ { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Asset Title", "searchField": "asset_title", "attributeType": "textbox", "isFeatured": false, "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "usedIn": { "metadataCascades": [], "metadataTables": [], "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ], "presets": [] } }, { "id": "63df1346-13dd-57g7-9cec-16349d87cg94", "name": "Asset Description", "searchField": "asset_description", "attributeType": "textarea", "isFeatured": false, "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "usedIn": { "metadataCascades": [], "metadataTables": [], "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ], "presets": [] } }, { "id": "77ab1234-11bb-22cc-33dd-44ee55ff6677", "name": "Publication Date", "searchField": "publication_date", "attributeType": "date", "isFeatured": false, "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "usedIn": { "metadataCascades": [], "metadataTables": [], "metadataGroups": [], "metadataTemplates": [], "presets": [] } }, { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category", "searchField": "asset_category", "attributeType": "dropdown", "isFeatured": true, "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "usedIn": { "metadataCascades": [], "metadataTables": [], "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Brand Guidelines" } ], "presets": [ { "id": "d4e5f6a7-8901-bcde-f123-456789012345", "name": "Default Preset" } ] } } ] } } } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Attribute_Type": { "value": { "message": "Invalid attributeType: must be one or more of textbox, textarea, date, dropdown" } }, "Invalid_In_Use": { "value": { "message": "Invalid inUse: must be true, false, or one of metadataCascades, metadataTables, metadataGroups, metadataTemplates, presets" } }, "Invalid_Filter_For": { "value": { "message": "Invalid filterFor: must be one of requestInbox" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/attribute": { "post": { "operationId": "CreateMetadataAttribute", "tags": [ "METADATA ATTRIBUTES" ], "summary": "(NEW!) Create Metadata Attribute", "description": "Create a new metadata attribute. Supports four attribute types: `textbox`, `textarea`, `date`, and `dropdown`. Each type has a distinct request schema and returns a type-specific response.\n\n**Business Rules:**\n- An attribute that is `isRequired: true` or `isTypeahead: true` cannot have `technicalMetadataMapping` values.\n- A required attribute cannot also be sensitive (`isRequired: true` and `isSensitive: true` cannot both be set).\n- `isFacetable: true` requires `isSearchable: true`.\n- Max character limit for textbox is 250 characters.\n- Max character limit for textarea is 10,000 characters.\n- Textarea attributes cannot be facetable or support typeahead.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the new metadata attribute. The schema varies by `attributeType`:\n- **textbox** — includes `isTypeahead`, `maxCharacterLength` (max 250), `technicalMetadataMapping`\n- **textarea** — includes `maxCharacterLength` (max 10000), `technicalMetadataMapping`. Cannot be facetable or typeahead.\n- **date** — minimal schema with shared fields only.\n- **dropdown** — includes `vocabularyId` (required), `multiSelect`, `synonyms`, `technicalMetadataMapping`", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/create-metadata-attribute-textbox" }, { "$ref": "#/components/schemas/create-metadata-attribute-textarea" }, { "$ref": "#/components/schemas/create-metadata-attribute-date" }, { "$ref": "#/components/schemas/create-metadata-attribute-dropdown" } ], "discriminator": { "propertyName": "attributeType", "mapping": { "textbox": "#/components/schemas/create-metadata-attribute-textbox", "textarea": "#/components/schemas/create-metadata-attribute-textarea", "date": "#/components/schemas/create-metadata-attribute-date", "dropdown": "#/components/schemas/create-metadata-attribute-dropdown" } } }, "examples": { "Textbox": { "summary": "Create a textbox attribute", "value": { "attributeType": "textbox", "name": "Asset Title", "tooltipText": "Enter the title of the asset", "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isTypeahead": true, "maxCharacterLength": 250, "technicalMetadataMapping": [] } }, "Textarea": { "summary": "Create a textarea attribute", "value": { "attributeType": "textarea", "name": "Asset Description", "tooltipText": "Enter the Description of the asset", "isRequired": true, "isSearchable": true, "isReadOnly": false, "isSensitive": false, "maxCharacterLength": 10000, "technicalMetadataMapping": [ "fileName", "fileType" ] } }, "Date": { "summary": "Create a date attribute", "value": { "attributeType": "date", "name": "Publication Date", "tooltipText": "The date this asset was published", "isRequired": false, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false } }, "Dropdown": { "summary": "Create a dropdown attribute", "value": { "attributeType": "dropdown", "name": "Asset Category", "tooltipText": "Select the category for this asset", "isRequired": true, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "vocabularyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "multiSelect": false, "technicalMetadataMapping": [ "category" ], "synonyms": [ { "valueId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "keywords": [ "campaign", "Campaigns", "campaigns" ] }, { "valueId": "4c5cf3b0-b930-4bb3-a36b-f2cfa515fb19", "keywords": [ "Out-of-Home", "OOH" ] } ] } } } } } }, "responses": { "200": { "description": "The newly created metadata attribute object. The response shape matches the `attributeType` sent in the request:\n- **textbox** — includes `maxCharacterLength`, `isTypeahead`, `technicalMetadataMapping`\n- **textarea** — includes `maxCharacterLength`, `isTypeahead` (always false), `technicalMetadataMapping`\n- **date** — shared fields only, `technicalMetadataMapping` is empty array\n- **dropdown** — includes `vocabularyId`, `isMultiSelect`, `synonyms`, `technicalMetadataMapping`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/metadata-attribute-textbox" }, { "$ref": "#/components/schemas/metadata-attribute-textarea" }, { "$ref": "#/components/schemas/metadata-attribute-date" }, { "$ref": "#/components/schemas/metadata-attribute-dropdown" } ], "discriminator": { "propertyName": "attributeType", "mapping": { "textbox": "#/components/schemas/metadata-attribute-textbox", "textarea": "#/components/schemas/metadata-attribute-textarea", "date": "#/components/schemas/metadata-attribute-date", "dropdown": "#/components/schemas/metadata-attribute-dropdown" } } }, "examples": { "Text Box Response": { "summary": "Textbox attribute created", "value": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Asset Title", "searchField": "asset_title", "attributeType": "textbox", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Enter the title of the asset", "technicalMetadataMapping": [], "maxCharacterLength": 250, "isTypeahead": true } }, "Text Area Response": { "summary": "Textarea attribute created", "value": { "id": "63df1346-13dd-57g7-9cec-16349d87cg94", "name": "Asset Description", "searchField": "asset_description", "attributeType": "textarea", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Enter the Description of the asset", "technicalMetadataMapping": [ "fileName", "fileType" ], "maxCharacterLength": 10000, "isTypeahead": false } }, "Date Response": { "summary": "Date attribute created", "value": { "id": "77ab1234-11bb-22cc-33dd-44ee55ff6677", "name": "Publication Date", "searchField": "publication_date", "attributeType": "date", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "isRequired": false, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "The date this asset was published", "technicalMetadataMapping": [] } }, "Dropdown Response": { "summary": "Dropdown attribute created", "value": { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category", "searchField": "asset_category", "attributeType": "dropdown", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "isRequired": true, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Select the category for this asset", "technicalMetadataMapping": [ "category" ], "vocabularyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "isMultiSelect": false, "synonyms": [ { "valueId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "keywords": [ "campaign", "Campaigns", "campaigns" ] }, { "valueId": "4c5cf3b0-b930-4bb3-a36b-f2cfa515fb19", "keywords": [ "Out-of-Home", "OOH" ] } ] } } } } } }, "400": { "description": "Bad request — business rule violation or invalid field value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/attribute/{id}": { "get": { "operationId": "GetMetadataAttribute", "tags": [ "METADATA ATTRIBUTES" ], "summary": "(NEW!) Get Metadata Attribute", "description": "Retrieve a single metadata attribute by its ID, returning the full attribute configuration including type-specific fields and `usedIn` references.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata attribute to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "41fd8f16-19d9-46c3-a1c0-5ab9d8e198f2" } } ], "responses": { "200": { "description": "The full metadata attribute object. The response shape varies by `attributeType`:\n- **textbox** — includes `maxCharacterLength`, `isTypeahead`, `technicalMetadataMapping`, `usedIn`\n- **textarea** — includes `maxCharacterLength`, `isTypeahead` (always false), `technicalMetadataMapping`, `usedIn`\n- **date** — shared fields plus `usedIn`\n- **dropdown** — includes `vocabulary` (object), `isMultiSelect`, `synonyms`, `technicalMetadataMapping`, `usedIn`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/metadata-attribute-textbox" }, { "$ref": "#/components/schemas/metadata-attribute-textarea" }, { "$ref": "#/components/schemas/metadata-attribute-date" }, { "$ref": "#/components/schemas/metadata-attribute-dropdown" } ], "discriminator": { "propertyName": "attributeType", "mapping": { "textbox": "#/components/schemas/metadata-attribute-textbox", "textarea": "#/components/schemas/metadata-attribute-textarea", "date": "#/components/schemas/metadata-attribute-date", "dropdown": "#/components/schemas/metadata-attribute-dropdown" } } }, "examples": { "Text Box Response": { "summary": "Textbox attribute", "value": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Asset Title", "searchField": "asset_title", "attributeType": "textbox", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Enter the title of the asset", "technicalMetadataMapping": [ "fileName", "assetName" ], "maxCharacterLength": 250, "isTypeahead": true, "usedIn": { "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Brand Guidelines" } ], "presets": [ { "id": "d4e5f6a7-8901-bcde-f123-456789012345", "name": "Default Preset" } ] } } }, "Text Area Response": { "summary": "Textarea attribute", "value": { "id": "63df1346-13dd-57g7-9cec-16349d87cg94", "name": "Asset Description", "searchField": "asset_description", "attributeType": "textarea", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Enter the Description of the asset", "technicalMetadataMapping": [ "fileName", "fileType" ], "maxCharacterLength": 10000, "isTypeahead": false, "usedIn": { "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ], "presets": [] } } }, "Date Response": { "summary": "Date attribute", "value": { "id": "77ab1234-11bb-22cc-33dd-44ee55ff6677", "name": "Publication Date", "searchField": "publication_date", "attributeType": "date", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "isRequired": false, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "The date this asset was published", "technicalMetadataMapping": [], "usedIn": { "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Brand Guidelines" } ], "presets": [ { "id": "d4e5f6a7-8901-bcde-f123-456789012345", "name": "Default Preset" } ] } } }, "Dropdown Response": { "summary": "Dropdown attribute", "value": { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category", "searchField": "asset_category", "attributeType": "dropdown", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "isRequired": true, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Select the category for this asset", "technicalMetadataMapping": [ "fileName" ], "vocabulary": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Asset Category List" }, "isMultiSelect": false, "synonyms": [ { "valueId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "keywords": [ "Test Synonym", "123 synonym" ] }, { "valueId": "4c5cf3b0-b930-4bb3-a36b-f2cfa515fb19", "keywords": [ "Synonym 456" ] } ], "usedIn": { "metadataGroups": [ { "id": "c1d2e3f4-1234-5678-abcd-ef1234567890", "name": "General Information" } ], "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "name": "Brand Guidelines" } ], "presets": [ { "id": "d4e5f6a7-8901-bcde-f123-456789012345", "name": "Default Preset" } ] } } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no attribute exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata attribute found for the provided ID" } } } } } }, "patch": { "operationId": "UpdateMetadataAttribute", "tags": [ "METADATA ATTRIBUTES" ], "summary": "(NEW!) Update Metadata Attribute", "description": "Partially update an existing metadata attribute. Only fields included in the request body will be updated — omitted fields remain unchanged.\n\n**Fields that cannot be updated:** `attributeType`, `vocabularyId`, `searchField`.\n\n**Business Rules (enforced on update):**\n- `isRequired: true` and `isSensitive: true` cannot both be set.\n- `isFacetable: true` requires `isSearchable: true`.\n- `isRequired: true` or `isTypeahead: true` cannot have `technicalMetadataMapping` values.\n- `maxCharacterLength` cannot exceed 250 for textbox or 10,000 for textarea.\n- Textarea attributes cannot be set to `isFacetable: true` or `isTypeahead: true`.\n- `isMultiSelect` can be changed from `false` to `true`, but NOT from `true` to `false`.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata attribute to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" } } ], "requestBody": { "description": "JSON object with fields to update. Only provided fields are applied. The available fields depend on the attribute type:\n- **textbox** — `name`, `tooltipText`, `isRequired`, `isSearchable`, `isFacetable`, `isReadOnly`, `isSensitive`, `maxCharacterLength`, `isTypeahead`, `technicalMetadataMapping`\n- **textarea** — `name`, `tooltipText`, `isRequired`, `isSearchable`, `isReadOnly`, `isSensitive`, `maxCharacterLength`, `technicalMetadataMapping`\n- **date** — `name`, `tooltipText`, `isRequired`, `isSearchable`, `isFacetable`, `isReadOnly`, `isSensitive`\n- **dropdown** — `name`, `tooltipText`, `isRequired`, `isSearchable`, `isFacetable`, `isReadOnly`, `isSensitive`, `isMultiSelect`, `technicalMetadataMapping`, `synonyms`", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/update-metadata-attribute-textbox" }, { "$ref": "#/components/schemas/update-metadata-attribute-textarea" }, { "$ref": "#/components/schemas/update-metadata-attribute-date" }, { "$ref": "#/components/schemas/update-metadata-attribute-dropdown" } ] }, "examples": { "Update Textbox": { "summary": "Update a textbox attribute", "value": { "name": "Updated Asset Title", "tooltipText": "Updated tooltip text", "isTypeahead": false, "maxCharacterLength": 100, "technicalMetadataMapping": [ "fileName" ] } }, "Update Textarea": { "summary": "Update a textarea attribute", "value": { "name": "Updated Description Field", "maxCharacterLength": 5000, "technicalMetadataMapping": [ "fileName" ] } }, "Update Date": { "summary": "Update a date attribute", "value": { "name": "Updated Publication Date", "isFacetable": true, "isSearchable": true } }, "Update Dropdown": { "summary": "Update a dropdown attribute", "value": { "isMultiSelect": true, "synonyms": [ { "valueId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "keywords": [ "Updated Synonym", "New keyword" ] } ] } } } } } }, "responses": { "200": { "description": "The full updated attribute object. The response shape matches the attribute's type:\n- **textbox** — includes `maxCharacterLength`, `isTypeahead`, `technicalMetadataMapping`\n- **textarea** — includes `maxCharacterLength`, `isTypeahead` (always false), `technicalMetadataMapping`\n- **date** — shared fields only\n- **dropdown** — includes `vocabularyId`, `isMultiSelect`, `synonyms`, `technicalMetadataMapping`", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/metadata-attribute-textbox" }, { "$ref": "#/components/schemas/metadata-attribute-textarea" }, { "$ref": "#/components/schemas/metadata-attribute-date" }, { "$ref": "#/components/schemas/metadata-attribute-dropdown" } ], "discriminator": { "propertyName": "attributeType", "mapping": { "textbox": "#/components/schemas/metadata-attribute-textbox", "textarea": "#/components/schemas/metadata-attribute-textarea", "date": "#/components/schemas/metadata-attribute-date", "dropdown": "#/components/schemas/metadata-attribute-dropdown" } } }, "examples": { "Textbox Updated": { "summary": "Textbox attribute after update", "value": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Updated Asset Title", "searchField": "asset_title", "attributeType": "textbox", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Updated tooltip text", "technicalMetadataMapping": [ "fileName" ], "maxCharacterLength": 100, "isTypeahead": false } }, "Textarea Updated": { "summary": "Textarea attribute after update", "value": { "id": "63df1346-13dd-57g7-9cec-16349d87cg94", "name": "Updated Description Field", "searchField": "asset_description", "attributeType": "textarea", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "isRequired": true, "isSearchable": true, "isFacetable": false, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Enter the Description of the asset", "technicalMetadataMapping": [ "fileName" ], "maxCharacterLength": 5000, "isTypeahead": false } }, "Date Updated": { "summary": "Date attribute after update", "value": { "id": "77ab1234-11bb-22cc-33dd-44ee55ff6677", "name": "Updated Publication Date", "searchField": "publication_date", "attributeType": "date", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "isRequired": false, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "The date this asset was published", "technicalMetadataMapping": [] } }, "Dropdown Updated": { "summary": "Dropdown attribute after update", "value": { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category", "searchField": "asset_category", "attributeType": "dropdown", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "isRequired": true, "isSearchable": true, "isFacetable": true, "isReadOnly": false, "isSensitive": false, "isSystem": false, "isVisible": true, "isRestricted": false, "isFeatured": false, "isSortByHitCount": false, "tooltipText": "Select the category for this asset", "technicalMetadataMapping": [], "vocabularyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "isMultiSelect": true, "synonyms": [ { "valueId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "keywords": [ "Updated Synonym", "New keyword" ] } ] } } } } } }, "400": { "description": "Bad request — business rule violation or invalid field value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Required_and_Sensitive": { "value": { "status": "error", "message": "A required attribute cannot also be marked as sensitive" } }, "Facetable_without_Searchable": { "value": { "status": "error", "message": "A facetable attribute must also be searchable" } }, "Textarea_Facetable": { "value": { "status": "error", "message": "A textarea attribute cannot be facetable" } }, "Required_with_TechMapping": { "value": { "status": "error", "message": "A required attribute cannot have technical metadata mappings" } }, "MultiSelect_Downgrade": { "value": { "status": "error", "message": "A multi-select dropdown cannot be converted to single-select" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no attribute exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata attribute found for the provided ID" } } } } } }, "delete": { "operationId": "DeleteMetadataAttribute", "tags": [ "METADATA ATTRIBUTES" ], "summary": "(NEW!) Delete Metadata Attribute", "description": "Permanently delete a metadata attribute by its ID. Deletion is blocked if the attribute is currently referenced by any metadata group or template.\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata attribute to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "41fd8f16-19d9-46c3-a1c0-5ab9d8e198f2" } } ], "responses": { "204": { "description": "No Content. The attribute has been permanently deleted." }, "400": { "description": "Bad request — attribute is currently in use and cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "status": "error", "message": "Attribute cannot be deleted as it is currently in use." } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no attribute exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata attribute found for the provided ID" } } } } } } }, "/metadata/groups": { "get": { "operationId": "ListMetadataGroups", "tags": [ "METADATA GROUPS" ], "summary": "(NEW!) List Metadata Groups (Paginated)", "description": "Retrieve a paginated list of metadata groups for UI consumption. Supports filtering by name and usage, pagination via offset, and sorting via query parameters.\n\nEach result includes an `inUse` flag, computed from whether `usedIn.metadataTemplates` is non-empty.\n\n**Defaults:**\n- `inUse` is unset by default, returning groups regardless of usage.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Partial, case-insensitive match against group name. When omitted, all groups are returned (subject to pagination).", "required": false, "schema": { "type": "string", "example": "general" } }, { "name": "inUse", "in": "query", "description": "Filters by usage status. `true` returns only groups referenced by at least one template; `false` returns only groups not referenced by any template. Omitted applies no filter.", "required": false, "schema": { "type": "boolean" } }, { "name": "from", "in": "query", "description": "Search offset from which results will start. Defaults to 0.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return. Defaults to 100. Maximum 100.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort by. Defaults to `groupName`.", "required": false, "schema": { "type": "string", "enum": [ "groupName", "createdEpoch", "lastUpdatedEpoch", "inUse" ], "default": "groupName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Paginated list of metadata groups.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-group-list" }, "examples": { "Metadata_Groups_Page": { "summary": "A page of metadata groups, showing the inUse field", "value": { "hitCount": 1, "results": [ { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Product Information", "searchField": "product_information", "isGroupNameVisible": false, "inUse": true, "createdEpoch": 1773070355217, "createdDate": "2026-03-20T12:05:27Z", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-20T12:05:27Z", "usedIn": { "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ] } } ] } } } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_In_Use": { "value": { "message": "Invalid inUse: must be true or false" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/group": { "post": { "operationId": "CreateMetadataGroup", "tags": [ "METADATA GROUPS" ], "summary": "(NEW!) Create Metadata Group", "description": "Create a new metadata group. A group has a name, an ordered list of attribute IDs, and an optional flag controlling whether the group name is visible.\n\nThe order of attributes in the request is preserved and reflected in the response.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the new metadata group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-metadata-group" } } } }, "responses": { "200": { "description": "The newly created metadata group object with resolved attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-group" }, "example": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Product Information", "searchField": "product_information", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-20T12:05:27Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-20T12:05:27Z", "isGroupNameVisible": false, "attributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "attributeType": "textbox" }, { "id": "b1feb2cd-ab35-4fc6-917a-37a2e8419167", "name": "SKU Details", "attributeType": "table" }, { "id": "187f9ef9-b1e7-4a33-95e3-8ee99206d9fc", "name": "Event Date", "attributeType": "date" }, { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "attributeType": "dropdown" } ] } } } }, "400": { "description": "Bad request — invalid request body or one or more attribute IDs do not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "One or more attribute IDs do not correspond to existing attributes" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/group/{id}": { "get": { "operationId": "GetMetadataGroup", "tags": [ "METADATA GROUPS" ], "summary": "(NEW!) Get Metadata Group", "description": "Retrieve a single metadata group by its ID, returning the full group configuration including the resolved ordered list of attributes and `usedIn` references.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata group to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" } } ], "responses": { "200": { "description": "The full metadata group object with resolved attributes and `usedIn` references.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-group" }, "example": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Product Information", "searchField": "product_information", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-20T12:05:27Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-20T12:05:27Z", "isGroupNameVisible": false, "usedIn": { "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ] }, "attributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "attributeType": "textbox" }, { "id": "b1feb2cd-ab35-4fc6-917a-37a2e8419167", "name": "SKU Details", "attributeType": "table" }, { "id": "187f9ef9-b1e7-4a33-95e3-8ee99206d9fc", "name": "Event Date", "attributeType": "date" }, { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "attributeType": "dropdown" } ] } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no group exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata group found for the provided ID" } } } } } }, "patch": { "operationId": "UpdateMetadataGroup", "tags": [ "METADATA GROUPS" ], "summary": "(NEW!) Update Metadata Group", "description": "Partially update an existing metadata group. Only fields included in the request body will be updated — omitted fields remain unchanged.\n\nWhen `attributeIds` is provided, the existing attribute list is fully replaced in the order given.\n\n**Fields that cannot be updated:** `searchField`.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata group to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" } } ], "requestBody": { "description": "JSON object with fields to update. Only provided fields are applied.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-metadata-group" }, "examples": { "Update Name": { "summary": "Update name only", "value": { "name": "Updated Group Name" } }, "Update Attributes": { "summary": "Update attributes list", "value": { "attributeIds": [ "01dc8715-c660-44cb-b3a4-70f4779e6651", "013ad220-b377-432d-bc6d-b1614dbb82c1" ] } } } } } }, "responses": { "200": { "description": "The full updated group object with resolved attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-group" }, "examples": { "Name_Updated": { "summary": "Group after name update", "value": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Updated Group Name", "searchField": "product_information", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-20T12:05:27Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-20T13:00:00Z", "isGroupNameVisible": false, "usedIn": { "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ] }, "attributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "attributeType": "textbox" }, { "id": "b1feb2cd-ab35-4fc6-917a-37a2e8419167", "name": "Product Specifications", "attributeType": "table" }, { "id": "187f9ef9-b1e7-4a33-95e3-8ee99206d9fc", "name": "Select Travel Date", "attributeType": "date" }, { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "attributeType": "dropdown" } ] } }, "Attributes_Updated": { "summary": "Group after attributes list update", "value": { "id": "52ce0235-02cc-46f6-8bdb-05238c76bf83", "name": "Product Information", "searchField": "product_information", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-20T12:05:27Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-20T13:00:00Z", "isGroupNameVisible": false, "usedIn": { "metadataTemplates": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "name": "Product Content" } ] }, "attributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "attributeType": "textbox" }, { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "attributeType": "dropdown" } ] } } } } } }, "400": { "description": "Bad request — one or more attribute IDs do not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "One or more attribute IDs do not correspond to existing attributes" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no group exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata group found for the provided ID" } } } } } }, "delete": { "operationId": "DeleteMetadataGroup", "tags": [ "METADATA GROUPS" ], "summary": "(NEW!) Delete Metadata Group", "description": "Permanently delete a metadata group by its ID. Deletion is blocked if the group is currently referenced by any metadata template.\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata group to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" } } ], "responses": { "204": { "description": "No Content. The group has been permanently deleted." }, "400": { "description": "Bad request — group is currently referenced by one or more metadata templates.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Group cannot be deleted as it is currently referenced by one or more metadata templates" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no group exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "No metadata group found for the provided ID" } } } } } } }, "/metadata/templates": { "get": { "operationId": "ListMetadataTemplates", "tags": [ "METADATA TEMPLATES" ], "summary": "(NEW!) List Metadata Templates (Paginated)", "description": "Retrieve a paginated list of metadata templates for UI consumption. Supports filtering by name, pagination via offset, and sorting via query parameters.\n\nEach result includes the full template object with `attributesDefaultValue`, `accessTemplates`, an `inUse` flag indicating whether the template is currently assigned to any assets, and an `indexStatus` indicating whether the template is ready to be assigned to assets.\n\n**Defaults:**\n- `includeDenormalized` defaults to `false`. `templateDenormalized` is only included in each result when `includeDenormalized` is `true`.\n- `inUse` is unset by default, returning templates regardless of usage.\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Partial, case-insensitive match against template name. When omitted, all templates are returned (subject to pagination).", "required": false, "schema": { "type": "string", "example": "video" } }, { "name": "from", "in": "query", "description": "Search offset from which results will start. Defaults to 0.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return. Defaults to 100. Maximum 100 — a `limit` above 100 is rejected with a 400 rather than being capped.", "required": false, "schema": { "type": "integer", "default": 100, "maximum": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort by. Defaults to `templateName`.", "required": false, "schema": { "type": "string", "enum": [ "templateName", "createdEpoch", "lastUpdatedEpoch", "inUse" ], "default": "templateName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "includeDenormalized", "in": "query", "description": "When `true`, includes `templateDenormalized` in each result. Defaults to `false`, in which case `templateDenormalized` is omitted from the response.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "inUse", "in": "query", "description": "Filters results by usage status. When omitted, templates are returned regardless of usage. `true` returns only templates currently assigned to assets; `false` returns only templates not currently assigned to any assets.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Paginated list of metadata templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "hitCount": { "type": "integer", "description": "Total number of templates matching the search criteria.", "example": 8 }, "results": { "type": "array", "description": "Array of template objects.", "items": { "type": "object", "properties": { "templateId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "customerId": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid" }, "createdEpoch": { "type": "integer" }, "createdDate": { "type": "string", "format": "date-time" }, "lastUpdatedBy": { "type": "string", "format": "uuid" }, "lastUpdatedEpoch": { "type": "integer" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "groupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "templateType": { "type": "array", "items": { "type": "string" } }, "attributesDefaultValue": { "type": "array", "items": { "type": "object", "properties": { "searchField": { "type": "string" }, "value": { "description": "Default value for the attribute." } } } }, "accessTemplates": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "inUse": { "type": "boolean", "description": "Whether this template is currently assigned to any assets." }, "indexStatus": { "type": "string", "description": "Whether the template is ready to be assigned to assets. The template can only be assigned to assets when `indexStatus` is `ready`.", "enum": [ "pending", "building", "ready", "failed" ] }, "templateDenormalized": { "type": "object", "description": "System-generated denormalized template structure. Only present in the response when the `includeDenormalized` query parameter is `true`.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "groupOrder": { "type": "integer" }, "metadataGroupName": { "type": "string" }, "isGroupNameVisible": { "type": "boolean" }, "metadataGroupSearchField": { "type": "string" }, "securityPermissions": { "type": "array", "items": { "type": "object" } }, "metadataAttributes": { "type": "array", "description": "Ordered list of attributes. Shape varies by `type`:\n- **text** (subType: textBox/textArea) — includes `length`, `techMetaMapping`\n- **controlledVocabulary** — includes `controlledVocabularyId`, `isMultipleSelect`\n- **date** — includes `dateFormat`\n- **tableAttribute** — includes `tableFieldsDenormalized`, `isSingleRow`, `isSmartTable`\n- **cascadeAttribute** — includes `cascadeMapId`, `cascadeFieldsDenormalized`", "items": { "oneOf": [ { "$ref": "#/components/schemas/template-attribute-text" }, { "$ref": "#/components/schemas/template-attribute-controlled-vocabulary" }, { "$ref": "#/components/schemas/template-attribute-date" }, { "$ref": "#/components/schemas/template-attribute-table" }, { "$ref": "#/components/schemas/template-attribute-cascade" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/template-attribute-text", "controlledVocabulary": "#/components/schemas/template-attribute-controlled-vocabulary", "date": "#/components/schemas/template-attribute-date", "tableAttribute": "#/components/schemas/template-attribute-table", "cascadeAttribute": "#/components/schemas/template-attribute-cascade" } } } } } } } } } } } } } }, "example": { "hitCount": 2, "results": [ { "templateId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "name": "Product Content", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "groupIds": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83", "2e2ba74d-02d0-41c8-8995-17e2d7a4f25f" ], "templateType": [ "asset" ], "attributesDefaultValue": [ { "searchField": "title", "value": "Test Assets" } ], "accessTemplates": [], "inUse": true, "indexStatus": "ready", "templateDenormalized": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Product Information", "isGroupNameVisible": false, "metadataGroupSearchField": "product_information", "securityPermissions": [], "metadataAttributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "type": "text", "subType": "textBox", "searchField": "product_name", "attributeOrder": 1, "length": 100, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "edb9d604-4598-4a44-bd1a-07663d3ad98c", "name": "Usage Mediums", "type": "controlledVocabulary", "searchField": "usage_mediums", "attributeOrder": 2, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": true, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "34abed31-4546-4f15-ae07-3d22b9b056d5" }, { "id": "36dd687d-1ffb-44ab-b57f-5f310ebe0ff3", "name": "AI Description", "type": "text", "subType": "textArea", "searchField": "ai_description", "attributeOrder": 3, "length": 5000, "tooltip": "Generative AI Asset Description", "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "ed0a638f-1b96-4bb0-a77d-022c92e89d84", "name": "Events", "type": "tableAttribute", "searchField": "events", "attributeOrder": 4, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "type": "controlledVocabulary", "searchField": "event_type", "fieldOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": true, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "880d52d8-3372-41f7-a715-dbdd729a29b7" }, { "id": "721b8cf5-91af-4715-aedb-8d15713ee908", "name": "Event Name", "type": "text", "subType": "textBox", "searchField": "event_name", "fieldOrder": 2, "length": 120, "tooltip": "", "visible": true, "required": true, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "8f8b3394-66db-4984-9b79-39cc721006e9", "name": "Event Date", "type": "date", "searchField": "event_date", "fieldOrder": 4, "visible": true, "required": false, "readonly": false, "facetable": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "MM/dd/yyyy", "techMetaMapping": "" } ] }, { "id": "546ca0d5-8214-4f48-a32b-457035898327", "name": "Country Region", "type": "tableAttribute", "searchField": "country_region", "attributeOrder": 5, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "5ec692fc-e03b-43f9-a3e4-966565bd6812", "name": "Country Region Cascade", "type": "cascadeAttribute", "searchField": "country_region_cascade", "fieldOrder": 1, "visible": true, "dateFormat": "N/A", "cascadeMapId": "cba796a5-7a5a-4efc-b3d8-03bfee5663f1", "cascadeNameVisible": true, "cascadeFieldsDenormalized": [ { "id": "f9589099-398e-4f3e-8deb-5811abac267e", "name": "Country", "type": "controlledVocabulary", "subType": "textBox", "searchField": "country", "cascadeOrder": 0, "visible": true, "required": true, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ef7575cf-1df4-4f05-ae12-08a07bb1f48e" }, { "id": "d3e6472e-adad-4ac7-a993-64ac425a4844", "name": "Region", "type": "controlledVocabulary", "subType": "textBox", "searchField": "region", "cascadeOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": true, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ab5c35b3-a053-4e90-821a-fa4da37615bc" } ] } ] } ] } ] } }, { "templateId": "f4a5b6c7-d8e9-0123-4567-89abcdef0123", "name": "Brand Guidelines", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "groupIds": [ "5d1f1f87-5f64-4e03-8a2b-2c7e77f85bcb" ], "templateType": [ "default" ], "attributesDefaultValue": [], "accessTemplates": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "inUse": false, "indexStatus": "building", "templateDenormalized": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Brand Assets", "isGroupNameVisible": true, "metadataGroupSearchField": "brand_assets", "securityPermissions": [], "metadataAttributes": [ { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category", "type": "controlledVocabulary", "searchField": "asset_category", "attributeOrder": 1, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" } ] } ] } } ] } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Invalid query parameters" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/template": { "get": { "operationId": "GetMetadataTemplates", "tags": [ "METADATA TEMPLATES" ], "summary": "Retrieve Metadata Templates", "description": "Retrieve all metadata templates available to the requesting user\n\nThe user submitting the request must have administrator rights to view metadata templates.\n\n**Average Response Time:** 492ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "responses": { "200": { "description": "The Response Body will be a JSON array of template objects.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataTemplate" } }, "example": [ { "template": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Product Information", "metadataGroupSearchField": "product_information", "securityPermissions": [], "metadataAttributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "type": "text", "subType": "textBox", "searchField": "product_name", "attributeOrder": 1, "length": 100, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "edb9d604-4598-4a44-bd1a-07663d3ad98c", "name": "Usage Mediums", "type": "controlledVocabulary", "searchField": "usage_mediums", "attributeOrder": 2, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": true, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "34abed31-4546-4f15-ae07-3d22b9b056d5" }, { "id": "36dd687d-1ffb-44ab-b57f-5f310ebe0ff3", "name": "AI Description", "type": "text", "subType": "textArea", "searchField": "ai_description", "attributeOrder": 3, "length": 5000, "tooltip": "Generative AI Asset Description", "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "ed0a638f-1b96-4bb0-a77d-022c92e89d84", "name": "Events", "type": "tableAttribute", "searchField": "events", "attributeOrder": 4, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "type": "controlledVocabulary", "searchField": "event_type", "fieldOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": true, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "880d52d8-3372-41f7-a715-dbdd729a29b7" }, { "id": "721b8cf5-91af-4715-aedb-8d15713ee908", "name": "Event Name", "type": "text", "subType": "textBox", "searchField": "event_name", "fieldOrder": 2, "length": 120, "tooltip": "", "visible": true, "required": true, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "8f8b3394-66db-4984-9b79-39cc721006e9", "name": "Event Date", "type": "date", "searchField": "event_date", "fieldOrder": 4, "visible": true, "required": false, "readonly": false, "facetable": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "MM/dd/yyyy", "techMetaMapping": "" } ] }, { "id": "546ca0d5-8214-4f48-a32b-457035898327", "name": "Country Region", "type": "tableAttribute", "searchField": "country_region", "attributeOrder": 5, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "5ec692fc-e03b-43f9-a3e4-966565bd6812", "name": "Country Region Cascade", "type": "cascadeAttribute", "searchField": "country_region_cascade", "fieldOrder": 1, "visible": true, "dateFormat": "N/A", "cascadeMapId": "cba796a5-7a5a-4efc-b3d8-03bfee5663f1", "cascadeNameVisible": true, "cascadeFieldsDenormalized": [ { "id": "f9589099-398e-4f3e-8deb-5811abac267e", "name": "Country", "type": "controlledVocabulary", "subType": "textBox", "searchField": "country", "cascadeOrder": 0, "visible": true, "required": true, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ef7575cf-1df4-4f05-ae12-08a07bb1f48e" }, { "id": "d3e6472e-adad-4ac7-a993-64ac425a4844", "name": "Region", "type": "controlledVocabulary", "subType": "textBox", "searchField": "region", "cascadeOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": true, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ab5c35b3-a053-4e90-821a-fa4da37615bc" } ] } ] } ] }, { "groupOrder": 2, "metadataGroupName": "System Group", "metadataGroupSearchField": "system_group", "securityPermissions": [], "metadataAttributes": [ { "id": "6c94bd07-fd20-4d0d-8ec7-346d62e3457e", "name": "System Metadata Templates", "type": "controlledVocabulary", "searchField": "system_metadata_templates", "attributeOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": true, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "controlledVocabularyId": "3d3bf963-42e1-4a97-9fdb-88bd35af8972" } ] } ], "templateId": "0a5d6320-7e8c-43f3-b32a-7a32bcf2b261", "templateName": "Product Shot", "createdEpoch": 1774035316248, "lastUpdatedEpoch": 1779214564563, "templateType": [ "default" ] } } ] } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "post": { "operationId": "CreateMetadataTemplate", "tags": [ "METADATA TEMPLATES" ], "summary": "(NEW!) Create Metadata Template", "description": "Create a new metadata template for admin use. The endpoint derives `customerId` from the authenticated user context, validates all referenced metadata groups and access templates, generates the denormalized template structure, and returns the created template object directly.\n\nFor templates with `templateType` including `action`, template-as-asset creation is triggered asynchronously after successful template creation.\n\n**Defaults:**\n- `templateType` defaults to `[\"default\"]` when omitted\n- `attributesDefaultValue` defaults to `[]` when omitted\n- `accessTemplates` defaults to `[]` when omitted\n\n**Validation:**\n- All provided `groupIds` must exist and be valid metadata groups for the customer\n- All provided `accessTemplates` must exist and be valid access templates for the customer\n- The system group is automatically included if not already provided\n- Duplicate group IDs are deduplicated while preserving order\n- Duplicate effective attributes across selected groups return 400\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token from authentication.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key (optional).", "required": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the new metadata template.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "name", "groupIds" ], "properties": { "name": { "type": "string", "description": "Display name of the metadata template.", "example": "Product Content" }, "groupIds": { "type": "array", "description": "Ordered list of metadata group IDs to include in the template.", "items": { "type": "string", "format": "uuid" }, "example": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83" ] }, "templateType": { "type": "array", "description": "Template type list. Defaults to `[\"default\"]`.", "items": { "type": "string", "enum": [ "default", "asset", "action" ] }, "default": [ "default" ], "example": [ "default" ] }, "attributesDefaultValue": { "type": "array", "description": "Default metadata values for fields in the template.", "items": { "type": "object", "properties": { "searchField": { "type": "string", "description": "The searchField of the attribute to set a default for." }, "value": { "description": "The default value. Type varies by attribute type (string, array, etc)." } } }, "example": [ { "searchField": "title", "value": "Test Asset" } ] }, "accessTemplates": { "type": "array", "description": "Access template IDs (security templates) associated to the template. Defaults to `[]`.", "items": { "type": "string", "format": "uuid" }, "default": [], "example": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ] } } } } } }, "responses": { "200": { "description": "The created metadata template object.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "customerId": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid" }, "createdEpoch": { "type": "integer" }, "createdDate": { "type": "string", "format": "date-time" }, "lastUpdatedBy": { "type": "string", "format": "uuid" }, "lastUpdatedEpoch": { "type": "integer" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "groupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "templateType": { "type": "array", "items": { "type": "string" } }, "attributesDefaultValue": { "type": "array", "items": { "type": "object", "properties": { "searchField": { "type": "string" }, "value": { "description": "Default value for the attribute." } } } }, "accessTemplates": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "templateDenormalized": { "type": "object", "description": "System-generated denormalized template structure including resolved metadataGroups." } } }, "example": { "templateId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "name": "Product Content", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-11T14:32:35Z", "groupIds": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83", "5d1f1f87-5f64-4e03-8a2b-2c7e77f85bcb" ], "templateType": [ "default" ], "attributesDefaultValue": [ { "searchField": "title", "value": "Test Asset" } ], "accessTemplates": [ "a1b2c3d4-e5f6-7890-abcd-ef1234567890" ], "templateDenormalized": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Product Information", "isGroupNameVisible": false, "metadataAttributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "type": "text", "searchField": "product_name" } ], "metadataGroupSearchField": "product_information" } ] } } } } }, "400": { "description": "Bad request — missing required fields, invalid group/access template IDs, or duplicate effective attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "One or more groupIds do not correspond to existing metadata groups" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "409": { "description": "Conflict — template name already exists for the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Metadata template name already exists." } } } } } } }, "/metadata/template/{id}": { "get": { "operationId": "GetMetadataTemplate", "tags": [ "METADATA TEMPLATES" ], "summary": "Get Metadata Template", "description": "\"Retrieve the metadata template and its attributes list by template ID \\n\\nThe user submitting the request to metadata template must have the **Metadata Template Management** security role privilege.\\n\\nIn response, it will contain the metadata groups template have and each group metadata attributes list.\"\n\n**Average Response Time:** 1406ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify a Metadata Template ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The full metadata template object with denormalized groups and attributes. The `metadataAttributes` array within each group contains attribute objects whose shape varies by `type`:\n- **text** (subType: textBox) — includes `length`, `typeahead`, `techMetaMapping`. Max 250 chars, supports faceting.\n- **text** (subType: textArea) — includes `length`, `techMetaMapping`. Max 10000 chars. Cannot be facetable or typeahead.\n- **controlledVocabulary** — includes `controlledVocabularyId`, `isMultipleSelect`\n- **date** — includes `dateFormat`\n- **tableAttribute** — includes `tableFieldsDenormalized`, `isSingleRow`, `isSmartTable`, `tableNameVisible`\n- **cascadeAttribute** — includes `cascadeMapId`, `cascadeFieldsDenormalized`, `cascadeNameVisible`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-template-detail" }, "examples": { "Full Template": { "summary": "Template with all attribute types", "value": { "templateId": "0a5d6320-7e8c-43f3-b32a-7a32bcf2b261", "templateName": "Product Shot", "createdEpoch": 1774035316248, "lastUpdatedEpoch": 1779214564563, "templateType": [ "default" ], "template": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Product Information", "metadataGroupSearchField": "product_information", "securityPermissions": [], "metadataAttributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "type": "text", "subType": "textBox", "searchField": "product_name", "attributeOrder": 1, "length": 100, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "edb9d604-4598-4a44-bd1a-07663d3ad98c", "name": "Usage Mediums", "type": "controlledVocabulary", "searchField": "usage_mediums", "attributeOrder": 2, "tooltip": "", "visible": true, "required": false, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": true, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "34abed31-4546-4f15-ae07-3d22b9b056d5" }, { "id": "36dd687d-1ffb-44ab-b57f-5f310ebe0ff3", "name": "AI Description", "type": "text", "subType": "textArea", "searchField": "ai_description", "attributeOrder": 3, "length": 5000, "tooltip": "Generative AI Asset Description", "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "ed0a638f-1b96-4bb0-a77d-022c92e89d84", "name": "Events", "type": "tableAttribute", "searchField": "events", "attributeOrder": 4, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "013ad220-b377-432d-bc6d-b1614dbb82c1", "name": "Event Type", "type": "controlledVocabulary", "searchField": "event_type", "fieldOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": true, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "", "controlledVocabularyId": "880d52d8-3372-41f7-a715-dbdd729a29b7" }, { "id": "721b8cf5-91af-4715-aedb-8d15713ee908", "name": "Event Name", "type": "text", "subType": "textBox", "searchField": "event_name", "fieldOrder": 2, "length": 120, "tooltip": "", "visible": true, "required": true, "readonly": false, "facetable": false, "sensitive": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "techMetaMapping": "" }, { "id": "8f8b3394-66db-4984-9b79-39cc721006e9", "name": "Event Date", "type": "date", "searchField": "event_date", "fieldOrder": 4, "visible": true, "required": false, "readonly": false, "facetable": false, "typeahead": false, "featured": true, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "MM/dd/yyyy", "techMetaMapping": "" } ] }, { "id": "546ca0d5-8214-4f48-a32b-457035898327", "name": "Country Region", "type": "tableAttribute", "searchField": "country_region", "attributeOrder": 5, "visible": true, "isSingleRow": false, "isSmartTable": false, "tableNameVisible": false, "dateFormat": "N/A", "tableFieldsDenormalized": [ { "id": "5ec692fc-e03b-43f9-a3e4-966565bd6812", "name": "Country Region Cascade", "type": "cascadeAttribute", "searchField": "country_region_cascade", "fieldOrder": 1, "visible": true, "dateFormat": "N/A", "cascadeMapId": "cba796a5-7a5a-4efc-b3d8-03bfee5663f1", "cascadeNameVisible": true, "cascadeFieldsDenormalized": [ { "id": "f9589099-398e-4f3e-8deb-5811abac267e", "name": "Country", "type": "controlledVocabulary", "subType": "textBox", "searchField": "country", "cascadeOrder": 0, "visible": true, "required": true, "readonly": false, "facetable": true, "sensitive": false, "typeahead": false, "featured": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ef7575cf-1df4-4f05-ae12-08a07bb1f48e" }, { "id": "d3e6472e-adad-4ac7-a993-64ac425a4844", "name": "Region", "type": "controlledVocabulary", "subType": "textBox", "searchField": "region", "cascadeOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": false, "sensitive": true, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "tooltip": "", "techMetaMapping": "", "controlledVocabularyId": "ab5c35b3-a053-4e90-821a-fa4da37615bc" } ] } ] } ] }, { "groupOrder": 2, "metadataGroupName": "System Group", "metadataGroupSearchField": "system_group", "securityPermissions": [], "metadataAttributes": [ { "id": "6c94bd07-fd20-4d0d-8ec7-346d62e3457e", "name": "System Metadata Templates", "type": "controlledVocabulary", "searchField": "system_metadata_templates", "attributeOrder": 1, "visible": true, "required": false, "readonly": false, "facetable": true, "typeahead": false, "isRestricted": false, "isMultipleSelect": false, "sortByHitCount": false, "dateFormat": "N/A", "controlledVocabularyId": "3d3bf963-42e1-4a97-9fdb-88bd35af8972" } ] } ] } } } } } } }, "400": { "description": "Wrong Template ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Metadata Template not found" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "patch": { "operationId": "UpdateMetadataTemplate", "tags": [ "METADATA TEMPLATES" ], "summary": "(NEW!) Update Metadata Template", "description": "Partially update an existing metadata template. Only fields included in the request body will be updated — omitted fields remain unchanged.\n\n**Updatable Fields:** `name`, `groupIds`, `attributesDefaultValue`, `accessTemplates`, `templateOverride`\n\n**Fields that cannot be updated:** `templateId`, `customerId`, `createdBy`, `createdEpoch`, `createdDate`, `templateType`, `templateDenormalized`, `dependencies`\n\n**Key Business Rules:**\n- Request body must contain at least one updatable field\n- Unknown or immutable fields are rejected with 400\n- `name` must be unique per customer (case-insensitive) — duplicate returns 409\n- `groupIds` must reference existing groups; system group is auto-appended last\n- Duplicate effective attributes across groups return 400\n- `accessTemplates` must reference existing access templates; can be cleared with `[]`\n- `attributesDefaultValue` keys must exist in the effective template\n- `templateDenormalized` is regenerated on every successful update\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token from authentication.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key (optional).", "required": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata template to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "8cd2c221-6a91-4dc6-9379-d55dca9d5313" } } ], "requestBody": { "description": "JSON object with fields to update. Only provided fields are applied.", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Display name of the metadata template.", "example": "Updated Product Template" }, "groupIds": { "type": "array", "description": "Attribute groups included in the template. Replaces existing list.", "items": { "type": "string", "format": "uuid" }, "example": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83", "5d1f1f87-5f64-4e03-8a2b-2c7e77f85bcb" ] }, "attributesDefaultValue": { "type": "array", "description": "Default metadata values for fields in the template.", "items": { "type": "object", "properties": { "searchField": { "type": "string" }, "value": { "description": "The default value." } } }, "example": [ { "searchField": "title", "value": "Test Assets" } ] }, "accessTemplates": { "type": "array", "description": "Access template IDs. Pass `[]` to clear.", "items": { "type": "string", "format": "uuid" }, "example": [] }, "templateOverride": { "type": "object", "description": "Template-level required/optional attribute overrides.", "properties": { "required": { "type": "array", "description": "searchFields to make required at the template level.", "items": { "type": "string" }, "example": [ "title" ] }, "optional": { "type": "array", "description": "searchFields to make optional at the template level.", "items": { "type": "string" }, "example": [ "country" ] } } } } }, "examples": { "Update Name": { "summary": "Update name only", "value": { "name": "Updated Product Template" } }, "Update Groups": { "summary": "Update groups", "value": { "groupIds": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83", "5d1f1f87-5f64-4e03-8a2b-2c7e77f85bcb" ] } }, "Update Defaults": { "summary": "Update default values", "value": { "attributesDefaultValue": [ { "searchField": "title", "value": "Test Assets" } ] } }, "Update Security": { "summary": "Update access templates", "value": { "accessTemplates": [] } }, "Update Override": { "summary": "Update whether an attribute is optional or required for this template.", "value": { "templateOverride": { "required": [ "title" ], "optional": [ "country" ] } } }, "Combined Update": { "summary": "Combined update", "value": { "name": "Updated Asset Template", "groupIds": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83" ], "attributesDefaultValue": [ { "searchField": "title", "value": "Test Assets" } ], "accessTemplates": [], "templateOverride": { "required": [ "title" ], "optional": [ "country" ] } } } } } } }, "responses": { "200": { "description": "The full updated template object including regenerated `templateDenormalized`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templateId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "customerId": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid" }, "createdEpoch": { "type": "integer" }, "createdDate": { "type": "string", "format": "date-time" }, "lastUpdatedBy": { "type": "string", "format": "uuid" }, "lastUpdatedEpoch": { "type": "integer" }, "lastUpdatedDate": { "type": "string", "format": "date-time" }, "groupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "templateType": { "type": "array", "items": { "type": "string" } }, "attributesDefaultValue": { "type": "array", "items": { "type": "object", "properties": { "searchField": { "type": "string" }, "value": { "description": "Default value for the attribute." } } } }, "accessTemplates": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "templateOverride": { "type": "object", "properties": { "required": { "type": "array", "items": { "type": "string" } }, "optional": { "type": "array", "items": { "type": "string" } } } }, "templateDenormalized": { "type": "object", "description": "System-generated denormalized template structure." } } }, "example": { "templateId": "8cd2c221-6a91-4dc6-9379-d55dca9d5313", "name": "Updated Asset Template", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "groupIds": [ "52ce0235-02cc-46f6-8bdb-05238c76bf83" ], "templateType": [ "asset" ], "attributesDefaultValue": [ { "searchField": "title", "value": "Test Assets" } ], "accessTemplates": [], "templateOverride": { "required": [ "title" ], "optional": [ "country" ] }, "templateDenormalized": { "metadataGroups": [ { "groupOrder": 1, "metadataGroupName": "Product Information", "isGroupNameVisible": false, "metadataAttributes": [ { "id": "01dc8715-c660-44cb-b3a4-70f4779e6651", "name": "Product Name", "type": "text", "searchField": "product_name" } ], "metadataGroupSearchField": "product_information" } ] } } } } }, "400": { "description": "Bad request — invalid field, immutable field, missing groups/security templates, or duplicate effective attributes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_GroupIds": { "value": { "status": "error", "message": "One or more groupIds do not correspond to existing metadata groups" } }, "Invalid_AccessTemplates": { "value": { "status": "error", "message": "One or more accessTemplates do not correspond to existing access templates" } }, "Immutable_Field": { "value": { "status": "error", "message": "Unexpected field [templateType] in metadata template update payload." } }, "Invalid_Default": { "value": { "status": "error", "message": "Attribute [unknown_search_field] is not valid for metadata template;" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no template exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Metadata Template not found" } } } }, "409": { "description": "Conflict — template name already exists for the customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "status": "error", "message": "Metadata template name already exists." } } } } } }, "delete": { "operationId": "DeleteMetadataTemplate", "tags": [ "METADATA TEMPLATES" ], "summary": "(NEW!) Delete Metadata Template", "description": "Permanently delete a metadata template by its ID. Deletion is blocked if the template has dependencies (e.g., assets using this template).\n\n**Delete Rules:**\n- Template must exist for the authenticated customer\n- Template ID must be a valid UUID\n- Template type must be one of `default`, `asset`, or `action`\n- Template cannot be deleted if it has dependencies (assets using it)\n- Related asset records are cleaned up\n- Deletion is recorded in `tenovos_delete_history`\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **Metadata Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token from authentication.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key (optional).", "required": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the metadata template to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e0d05152-9d1b-4b1e-bcb2-e762d195ec68" } } ], "responses": { "204": { "description": "No Content. The template has been permanently deleted." }, "400": { "description": "Bad request — template is currently in use by one or more assets and cannot be deleted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "status": "error", "message": "Metadata Template cannot be deleted as it is currently in use." } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Metadata Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no metadata template exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Metadata Template not found" } } } } } } }, "/storyboards": { "get": { "operationId": "ListStoryBoards", "tags": [ "STORY BOARDS" ], "summary": "(NEW!) List Story Boards", "description": "Retrieve a paginated list of Story Boards. Supports cursor-based pagination, search by title/description, sorting, and filtering by publish status and locale.\n\n**Access Control:**\n- Only Story Boards the user has view access to are returned\n- If the user does not have the `viewStoryboards` role privilege, an empty array is returned\n- Only published boards are returned unless the user has Story Board management permission\n- Permissions (`canDelete`, `canApplySecurityTemplates`, `canShareInternal`, `canShareExternal`, `canPublish`) are resolved server-side based on the user's role privileges and security template permissions\n\n**Pagination:**\n- Uses cursor-based pagination for consistent results across large and changing lists\n- Always use the same `sortBy` and `sortOrder` values across all pages of a paginated request\n- If sort parameters change, discard the current cursor and start a new request\n\nThe user submitting the request must have the **viewStoryboards** role privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Bearer token from authentication.", "required": true, "schema": { "type": "string" } }, { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Cursor for pagination. Omit on the first request. Use the `nextCursor` value from the previous response for subsequent pages.", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to 50. Maximum 100.", "required": false, "schema": { "type": "integer", "default": 50, "maximum": 100, "example": 50 } }, { "name": "search", "in": "query", "description": "Search term for filtering by title and description (partial, case-insensitive match).", "required": false, "schema": { "type": "string", "example": "fashion" } }, { "name": "sortBy", "in": "query", "description": "Field to sort by. Defaults to `updatedAt`.", "required": false, "schema": { "type": "string", "enum": [ "updatedAt", "title" ], "default": "updatedAt" } }, { "name": "sortOrder", "in": "query", "description": "Sort direction. Defaults to `desc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "status", "in": "query", "description": "Filter by publish status. Defaults to `all` for users with management permission.", "required": false, "schema": { "type": "string", "enum": [ "all", "published", "unpublished" ], "default": "all" } }, { "name": "locale", "in": "query", "description": "Filter by locale. Defaults to returning all locales if omitted.", "required": false, "schema": { "type": "string", "example": "en" } } ], "responses": { "200": { "description": "Paginated list of Story Boards.", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "description": "Array of Story Board objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the Story Board." }, "title": { "type": "string", "description": "Display title of the Story Board." }, "description": { "type": "string", "nullable": true, "description": "Description of the Story Board. Null if not set." }, "isPublished": { "type": "boolean", "description": "Whether the Story Board is currently published." }, "locale": { "type": "string", "description": "Locale of the Story Board. Defaults to \"en\" if not set." }, "hero": { "type": "object", "description": "Hero/banner image configuration.", "properties": { "assetId": { "type": "string", "format": "uuid", "nullable": true, "description": "Asset ID of the hero image." }, "imageUrl": { "type": "string", "nullable": true, "description": "Resolved URL of the hero image." }, "bannerFocusX": { "type": "number", "nullable": true, "description": "Horizontal focal point percentage (0-100)." }, "bannerFocusY": { "type": "number", "nullable": true, "description": "Vertical focal point percentage (0-100)." } } }, "counts": { "type": "object", "description": "Resolved content block counts.", "properties": { "collections": { "type": "integer", "description": "Number of collection blocks." }, "savedSearches": { "type": "integer", "description": "Number of saved search blocks." }, "totalBlocks": { "type": "integer", "description": "Total number of content blocks." } } }, "createdBy": { "type": "object", "description": "User who created the Story Board.", "properties": { "userId": { "type": "string", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true } } }, "updatedBy": { "type": "object", "description": "User who last updated the Story Board.", "properties": { "userId": { "type": "string", "format": "uuid", "nullable": true }, "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "avatarUrl": { "type": "string", "nullable": true } } }, "timestamps": { "type": "object", "description": "Creation and update timestamps.", "properties": { "createdAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date." }, "updatedAt": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last updated date." }, "updatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds." } } }, "permissions": { "type": "object", "description": "Resolved permissions for the current user on this Story Board.", "properties": { "canApplySecurityTemplates": { "type": "boolean" }, "canDelete": { "type": "boolean" }, "canShareInternal": { "type": "boolean" }, "canShareExternal": { "type": "boolean" }, "canPublish": { "type": "boolean" } } } } } }, "pageInfo": { "type": "object", "description": "Pagination metadata.", "properties": { "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page. Null if no more pages." }, "hasNextPage": { "type": "boolean", "description": "Whether there are more results after this page." }, "totalCount": { "type": "integer", "description": "Total number of Story Boards matching the query." } } } } }, "example": { "items": [ { "id": "d0d67c3c-8109-43a6-8e52-96eb11fcf74b", "title": "Iconic Fashion Week 2026", "description": "Latest in fashion and beauty from our worldwide brands.", "isPublished": true, "locale": "en", "hero": { "assetId": "cfec3d43-0f9b-4531-a418-cf5bdc40eba9", "imageUrl": "https://content.tenovos.io/customer/hero-fashion-week.png", "bannerFocusX": 49.5, "bannerFocusY": 30.6 }, "counts": { "collections": 1, "savedSearches": 0, "totalBlocks": 1 }, "createdBy": { "userId": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "firstName": "Brian", "lastName": "Fancett", "avatarUrl": "https://content.tenovos.io/customer/avatar/brian.jpeg" }, "updatedBy": { "userId": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "firstName": "Brian", "lastName": "Fancett", "avatarUrl": "https://content.tenovos.io/customer/avatar/brian.jpeg" }, "timestamps": { "createdAt": "2026-04-30T16:39:59.855Z", "updatedAt": "2026-04-30T16:50:41.575Z", "updatedEpoch": 1777567841575 }, "permissions": { "canApplySecurityTemplates": true, "canDelete": true, "canShareInternal": true, "canShareExternal": true, "canPublish": true } }, { "id": "80e5fd46-d8af-4097-a905-764ed7768908", "title": "Spring Campaign Assets", "description": "Curated assets for the Q2 spring campaign launch.", "isPublished": false, "locale": "en", "hero": { "assetId": "09e56143-dba0-4c9c-8862-fb4ea3b3985d", "imageUrl": "https://content.tenovos.io/customer/hero-spring-campaign.png", "bannerFocusX": 49.7, "bannerFocusY": 7 }, "counts": { "collections": 4, "savedSearches": 0, "totalBlocks": 4 }, "createdBy": { "userId": "dc63db1b-1e63-43bc-877e-418931b6895c", "firstName": "Kraeton", "lastName": "Moll", "avatarUrl": "https://content.tenovos.io/customer/avatar/kraeton.jpeg" }, "updatedBy": { "userId": "dc63db1b-1e63-43bc-877e-418931b6895c", "firstName": "Kraeton", "lastName": "Moll", "avatarUrl": "https://content.tenovos.io/customer/avatar/kraeton.jpeg" }, "timestamps": { "createdAt": "2026-05-13T17:42:26.479Z", "updatedAt": "2026-05-13T17:44:36.044Z", "updatedEpoch": 1778694276044 }, "permissions": { "canApplySecurityTemplates": true, "canDelete": true, "canShareInternal": true, "canShareExternal": true, "canPublish": true } } ], "pageInfo": { "nextCursor": null, "hasNextPage": false, "totalCount": 2 } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. User lacks viewStoryboards role privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/vocabularies": { "get": { "operationId": "ListMetadataVocabularies", "tags": [ "METADATA VOCABULARIES" ], "summary": "(NEW!) List Controlled Vocabularies (Paginated)", "description": "Retrieve a paginated, searchable list of controlled vocabularies for UI consumption. Response fields are lightweight by default (`valueCount` only); each vocabulary's values are returned per row via the `include` query parameter.\n\n**Defaults:**\n- `sortField` defaults to `name`.\n- `order` defaults to `asc`.\n- `from` defaults to `0`.\n- `limit` defaults to `100`, maximum `100`.\n- `includeSystem` defaults to `false`.\n- `searchTerm`, `inUse`, and `include` are unset by default, applying no filter.\n\n**Business Rules:**\n- `searchTerm` is a case-insensitive partial match on vocabulary `name`. It is trimmed before use, so a blank or whitespace-only value is treated as if omitted.\n- `order` is matched case-insensitively — `asc`, `ASC`, and `Asc` are equivalent.\n- `limit` above the maximum is **silently capped, not rejected**. `limit=500` returns 100 results and no error. A `limit` below `1` or a non-integer `limit` is still rejected with a 400. This differs from `GET /metadata/templates` and `GET /attributes`, which reject an over-maximum `limit` with a 400.\n- `inUse` accepts a boolean (`true`/`false` — aggregate: used anywhere at all) or one of `metadataAttributes`, `metadataCascades`, `metadataTables`, `metadataGroups`, `metadataTemplates`, filtering to vocabularies referenced in that specific usage category. Omitted applies no filter. `inUse` is also a valid `sortField` value.\n- `includeSystem` defaults to `false`. When `true`, also returns platform-owned system vocabularies used internally by various platform functionalities, alongside user-created ones.\n- `include` is a comma-separated list; `values` is currently the only accepted entry. Omitted returns summary fields only (`valueCount`); `include=values` adds `values[]` to each row. Unlike `GET /metadata/cascades`, `include=values` does **not** clamp `limit`.\n- `usedIn` is shaped `{ metadataAttributes: [], metadataCascades: [], metadataTables: [], metadataGroups: [], metadataTemplates: [] }`. A vocabulary's only direct reference is a dropdown attribute pointing at it, so `metadataAttributes` is the direct edge and the remaining categories are rollups through it. This shape is deliberately not the same as `GET /attributes`' `usedIn`, which carries a `presets` category and no `metadataAttributes`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive partial match on vocabulary name. Trimmed before use — a blank or whitespace-only value is treated as if omitted.", "required": false, "schema": { "type": "string", "example": "usage" } }, { "name": "inUse", "in": "query", "description": "Filters by usage status. `true`/`false` filters on aggregate usage (referenced anywhere at all). One of `metadataAttributes`, `metadataCascades`, `metadataTables`, `metadataGroups`, `metadataTemplates` filters to vocabularies referenced in that specific usage category. Omitted applies no filter.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "metadataAttributes", "metadataCascades", "metadataTables", "metadataGroups", "metadataTemplates" ] }, "examples": { "Referenced_In_Attributes": { "summary": "GET /metadata/vocabularies?inUse=metadataAttributes", "description": "Returns only vocabularies backing at least one dropdown attribute.", "value": "metadataAttributes" }, "Referenced_In_Templates": { "summary": "GET /metadata/vocabularies?inUse=metadataTemplates", "description": "Returns only vocabularies that reach at least one Template.", "value": "metadataTemplates" }, "Unused": { "summary": "GET /metadata/vocabularies?inUse=false", "description": "Returns only vocabularies that are not referenced anywhere at all.", "value": "false" } } }, { "name": "includeSystem", "in": "query", "description": "When `true`, also returns platform-owned system vocabularies used internally by various platform functionalities, in addition to user-created ones. Defaults to `false`.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Must be an integer of `0` or greater. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, minimum `1`, maximum `100`. A value above `100` is silently capped at `100` rather than rejected — the request succeeds and returns at most 100 results. A value below `1`, or a non-integer, is rejected with a 400.", "required": false, "schema": { "type": "integer", "default": 100, "minimum": 1, "maximum": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `name`.", "required": false, "schema": { "type": "string", "enum": [ "name", "createdEpoch", "lastUpdatedEpoch", "inUse", "valueCount" ], "default": "name" } }, { "name": "order", "in": "query", "description": "Sort direction. Matched case-insensitively. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "include", "in": "query", "description": "Comma-separated additional data to return per row. `values` is currently the only accepted entry, adding `values[]` to each result. Omitted returns summary fields only.", "required": false, "schema": { "type": "string", "enum": [ "values" ], "example": "values" } } ], "responses": { "200": { "description": "Paginated list of controlled vocabularies.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-vocabulary-list" }, "examples": { "Default Page": { "summary": "A page of vocabularies with summary fields only", "value": { "hitCount": 14, "results": [ { "id": "34abed31-4546-4f15-ae07-3d22b9b056d5", "name": "Usage Mediums", "searchField": "usage_mediums", "type": "controlledVocabulary", "featured": null, "valueCount": 12, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1771432800000, "lastUpdatedDate": "2026-02-18T16:40:00Z", "inUse": true, "usedIn": { "metadataAttributes": [ { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category" } ], "metadataCascades": [], "metadataTables": [], "metadataGroups": [ { "id": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42", "name": "Retail Assets" } ], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } ] } }, "Include Values": { "summary": "include=values adds the vocabulary's values to each row", "value": { "hitCount": 14, "results": [ { "id": "34abed31-4546-4f15-ae07-3d22b9b056d5", "name": "Usage Mediums", "searchField": "usage_mediums", "type": "controlledVocabulary", "featured": null, "valueCount": 3, "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "Digital" }, { "id": "a71c3e58-2b94-4d16-8f7a-3c5e9d1b2a48", "name": "Print" }, { "id": "c58e1f3a-4d72-4b89-9e16-5a3c7d9b2e14", "name": "Out of Home" } ], "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1771432800000, "lastUpdatedDate": "2026-02-18T16:40:00Z", "inUse": true, "usedIn": { "metadataAttributes": [ { "id": "99ff8765-aa11-bb22-cc33-dd44ee55ff66", "name": "Asset Category" } ], "metadataCascades": [], "metadataTables": [], "metadataGroups": [], "metadataTemplates": [] } } ] } } } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField. Allowed values: name, createdEpoch, lastUpdatedEpoch, inUse, valueCount" } }, "Invalid_Order": { "value": { "status": "error", "message": "Invalid order. Allowed values: asc, desc" } }, "Invalid_In_Use": { "value": { "status": "error", "message": "Invalid inUse. Allowed values: true, false, metadataAttributes, metadataCascades, metadataTables, metadataGroups, metadataTemplates" } }, "Invalid_Include": { "value": { "status": "error", "message": "Invalid [include] value [levels]. Supported values are [values]" } }, "Invalid_From": { "value": { "status": "error", "message": "Invalid from. Must be an integer >= 0" } }, "Invalid_Limit": { "value": { "status": "error", "message": "Invalid limit. Must be an integer >= 1" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } } } } }, "/metadata/vocabulary": { "get": { "operationId": "GetAllControlledVocab", "tags": [ "METADATA VOCABULARIES" ], "summary": "Get Controlled Vocabularies", "description": "Retrieve all the controlled vocabularies available to the current user.\n\nIn response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc.\n\n**Average Response Time:** 592ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body will be a JSON-formatted list including the following properties.\n- **metadata**: Vocabulary metadata\n - **values**: Key/Value list\n - **valueId** \n - **valueName**\n - **searchable**: Toggle searchability \n- **metadataDefinitionId**\n- **metadataDefinitionName**\n- **metadataDefinitionSearchField**: Map search field for this metadata definition\n- **metadataDefinitionType**: Metadata definition type\n- **createdEpoch**: Create time in milliseconds\n- **lastUpdatedEpoch**: Update time in milliseconds", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ControlledVocabulary" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "post": { "operationId": "CreateControlledVocab", "tags": [ "METADATA VOCABULARIES" ], "summary": "Create Controlled Vocabulary", "description": "Create a Controlled Vocabulary. User must have permission to create a controlled vocabulary.\n\nResponse will contain the object of the metadata definition attributes, such as id, name, type and search fields, etc.\n\n**Average Response Time:** 585ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledVocabularyCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledVocabularyResponse" } } } }, "400": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_Name": { "value": { "message": "name cannot be empty" } }, "Missing_Value": { "value": { "message": "value cannot be empty" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/vocabulary/{id}": { "get": { "operationId": "GetControlledVocab", "tags": [ "METADATA VOCABULARIES" ], "summary": "Get Controlled Vocabulary", "description": "Retrieve the Controlled Vocabulary and its attributes by Controlled Vocabulary Id\n\nIn response, it will contain the list of metadata key/value pair and metadata definition attributes like id, name, type and search fields etc.\n\n**Average Response Time:** 472ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a Controlled Vocabulary ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledVocabularyResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Wrong ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Controlled vocabulary not found" } } } } } }, "delete": { "operationId": "DeleteControlledVocab", "tags": [ "METADATA VOCABULARIES" ], "summary": "Delete Controlled Vocabulary", "description": "Delete a Controlled Vocabulary.\n\n**Average Response Time:** 130ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a Controlled Vocabulary ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "example": { "status": "success", "message": "Metadata Definition delete operation succeeded" } } } }, "400": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Token": { "value": { "message": "Invalid token specified: Cannot read properties of undefined (reading 'replace')" } } } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Wrong ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VocabularyDeleteErrorResponse" }, "example": { "message": "Controlled vocabulary not found" } } } } } }, "patch": { "operationId": "UpdateControlledVocab", "tags": [ "METADATA VOCABULARIES" ], "summary": "Update Controlled Vocabulary", "description": "Update a Controlled Vocabulary. User must have permission to update a controlled vocabulary.\n\nIn response, it will contain the object of metadata definition attributes like id, name, type and search fields etc.\n\n**Average Response Time:** 1462ms (Add Controlled Vocabulary (CV) value)\n**Average Response Time:** 716ms (Update a CV value )", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "Specify a Controlled Vocabulary ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body will be a JSON-formatted object including the following properties. Each property here is an operation. All of these operations can be applied in a single request. After updating the Controlled Vocabulary, execute */metadata/apply* POST request to apply the new changes.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledVocabularyUpdateRequest" }, "examples": { "Change_Name": { "$ref": "#/components/examples/ControlledVocabularyNameChange" }, "Add_Values": { "$ref": "#/components/examples/ControlledVocabularyAdd" }, "Update_Values": { "$ref": "#/components/examples/ControlledVocabularyUpdate" }, "Delete_Values": { "$ref": "#/components/examples/ControlledVocabularyDelete" } } } }, "required": true }, "responses": { "200": { "description": "The response is a JSON-formatted object keyed by the operation(s) performed. Each key — `name`, `add`, `update`, or `delete` — maps to the updated Controlled Vocabulary definition. When multiple operations are submitted in a single request, the response contains a key for each operation performed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ControlledVocabularyUpdateResponse" }, "examples": { "Change_Name": { "$ref": "#/components/examples/ControlledVocabularyNameChangeResp" }, "Add_Value": { "$ref": "#/components/examples/ControlledVocabularyAddResp" }, "Update_Values": { "$ref": "#/components/examples/ControlledVocabularyUpdateResp" }, "Delete_Values": { "$ref": "#/components/examples/ControlledVocabularyDeleteResp" } } } } }, "400": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Invalid token specified: Cannot read properties of undefined (reading 'replace')" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Wrong ID", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Controlled vocabulary not found" } } } } } } }, "/metadata/apply": { "post": { "operationId": "ApplyMetadataChanges", "tags": [ "METADATA TEMPLATES" ], "summary": "Apply Metadata Definition Changes", "description": "Apply the metadata definition changes. Use this operation after making any modification in metadata.\n\nIn response, it will contain the object of metadata definition attributes like id, name, type and search fields etc.\n\n**Average Response Time:** 53ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Changes applied successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetadataApplyResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/metadata/cascades": { "get": { "operationId": "ListMetadataCascades", "tags": [ "METADATA CASCADES" ], "summary": "(NEW!) List Metadata Cascades (Paginated)", "description": "Retrieve a paginated, searchable list of metadata cascades for UI consumption. Response fields are lightweight by default (counts only); full level/value detail is available via `GET /metadata/cascades/{id}` or via the `include` query parameter.\n\n**Defaults:**\n- `sortField` defaults to `name`.\n- `order` defaults to `asc`.\n- `from` defaults to `0`.\n- `limit` defaults to `100` — or `20` if `include` contains `values`, regardless of the value requested.\n\n**Business Rules:**\n- `searchTerm` is a case-insensitive partial match on cascade `name`.\n- `inUse` accepts a boolean (`true`/`false` — aggregate: used anywhere at all) or one of `metadataTables`, `metadataGroups`, `metadataTemplates`, filtering to cascades referenced in that specific usage category. Omitted applies no filter. `inUse` is also a valid `sortField` value.\n- `includeSystem` defaults to `false`. When `true`, also returns read-only, platform-owned cascades used internally by various platform functionalities, alongside user-created ones. System cascades cannot be edited or deleted by users.\n- `include` is a comma-separated list of `levels`, `values`. Omitted returns summary fields only (`levelCount`/`valueCount`); `include=levels` adds `levels[]` per row; `include=values` adds `values[]` per row and clamps `limit` to `20`; `include=levels,values` returns both.\n- `usedIn` is shaped `{ metadataTables: [], metadataGroups: [], metadataTemplates: [] }` — `metadataGroups` is a derived, transitive rollup through Table → group, and `metadataTemplates` a further rollup through group → template; neither is a direct reference.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive partial match on cascade name.", "required": false, "schema": { "type": "string" } }, { "name": "inUse", "in": "query", "description": "Filters by usage status. `true`/`false` filters on aggregate usage (referenced anywhere at all). One of `metadataTables`, `metadataGroups`, `metadataTemplates` filters to cascades referenced in that specific usage category. Omitted applies no filter.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "metadataTables", "metadataGroups", "metadataTemplates" ] }, "examples": { "Referenced_In_Tables": { "summary": "GET /metadata/cascades?inUse=metadataTables", "description": "Returns only cascades referenced directly in at least one Table.", "value": "metadataTables" }, "Referenced_In_Groups": { "summary": "GET /metadata/cascades?inUse=metadataGroups", "description": "Returns only cascades that transitively reach at least one group (Table → group) — i.e. cascades present in a group.", "value": "metadataGroups" }, "Referenced_In_Templates": { "summary": "GET /metadata/cascades?inUse=metadataTemplates", "description": "Returns only cascades that transitively reach at least one Template (Table → group → template).", "value": "metadataTemplates" } } }, { "name": "includeSystem", "in": "query", "description": "When `true`, also returns read-only, platform-owned cascades used internally by various platform functionalities, in addition to user-created ones. System cascades cannot be edited or deleted by users. Defaults to `false`.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, maximum `100` — clamped to `20` when `include` contains `values`.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `name`.", "required": false, "schema": { "type": "string", "enum": [ "name", "createdEpoch", "lastUpdatedEpoch", "inUse" ], "default": "name" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "include", "in": "query", "description": "Comma-separated additional data to return per row. `levels`, `values`, or both. Omitted returns summary fields only.", "required": false, "schema": { "type": "string", "example": "levels,values" } } ], "responses": { "200": { "description": "Paginated list of metadata cascades.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-cascade-list" }, "examples": { "Default Page": { "summary": "A page of cascades with summary fields only", "value": { "hitCount": 9, "results": [ { "id": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "name": "Region Cascade", "searchField": "region_cascade", "nameVisible": true, "featured": null, "levelCount": 2, "valueCount": 12, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1771432800000, "lastUpdatedDate": "2026-02-18T16:40:00Z", "inUse": true, "usedIn": { "metadataTables": [ { "id": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83", "name": "Store Locations Table" } ], "metadataGroups": [ { "id": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42", "name": "Retail Assets" } ], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } ] } }, "Include Values": { "summary": "include=values clamps limit to 20 and adds the values tree per row", "value": { "hitCount": 9, "results": [ { "id": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "name": "Region Cascade", "valueCount": 12, "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "North America", "source": null, "children": [] } ] } ] } } } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField: must be one of name, createdEpoch, lastUpdatedEpoch, inUse" } }, "Invalid_Include": { "value": { "status": "error", "message": "Invalid include: must be a comma-separated combination of levels, values" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } } } }, "post": { "operationId": "CreateMetadataCascade", "tags": [ "METADATA CASCADES" ], "summary": "(NEW!) Create Metadata Cascade", "description": "Create a metadata cascade — its level schema and initial value tree — as one merged resource, in a single call. This replaces what was previously two separate writes (create the attribute, then create its value map); there is no longer a separate map/attribute split at all.\n\n**Defaults:**\n- `nameVisible` defaults to `true`.\n\n**Business Rules:**\n- `levels` must contain at most 4 entries. Each `attributeId` must reference an existing, single-select controlled-vocabulary attribute.\n- `values` may be omitted to create an empty cascade. Nesting depth via `children` must not exceed `levels.length` (and therefore can never exceed 4). No two nodes in the submitted tree may share the same `id`.\n- `searchField` is optional. Omitted, it is generated server-side. Supplied, it is used as-is and the cascade is created as featured (`featured: true`). Either way it is permanently fixed thereafter.\n- A duplicate `name`/`searchField` is rejected with `409`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the cascade to create. Required: `name`, `levels`. Optional: `nameVisible` (defaults to `true`), `searchField` (creates a featured cascade), `values` (may be omitted to create an empty cascade).", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-metadata-cascade" }, "examples": { "Create With Values": { "summary": "Create a cascade with an initial value tree", "value": { "name": "Region Cascade", "nameVisible": true, "levels": [ { "order": 0, "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" }, { "order": 1, "attributeId": "c8b6d4f2-1a3e-4c9b-8f7d-3e2a9c5b1d64" } ], "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "North America", "children": [ { "id": "7b2e9c4a-3f1d-4e8b-9a6c-5d0f2a7b3e91", "name": "United States", "children": [] } ] } ] } }, "Create Empty": { "summary": "Create a cascade with no values yet", "value": { "name": "Region Cascade", "levels": [ { "order": 0, "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" } ] } }, "Create Featured": { "summary": "Create a featured cascade with an explicit searchField", "value": { "name": "Region Cascade", "searchField": "region_cascade", "levels": [ { "order": 0, "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" } ] } } } } } }, "responses": { "201": { "description": "Created. Returns the complete cascade detail, mirroring `GET /metadata/cascades/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-cascade-detail" }, "examples": { "Created_Cascade": { "summary": "Newly created cascade", "value": { "id": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "name": "Region Cascade", "searchField": "region_cascade", "levels": [ { "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70", "attributeName": "Continent", "order": 0 } ], "nameVisible": true, "featured": true, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1770714900000, "lastUpdatedDate": "2026-02-10T09:15:00Z", "usedIn": { "metadataTables": [], "metadataGroups": [], "metadataTemplates": [] }, "values": [] } } } } } }, "400": { "description": "Bad request — missing required field, an invalid `levels`/`values` shape, or a `levels[].attributeId` that isn't a single-select controlled vocabulary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Too_Many_Levels": { "value": { "status": "error", "message": "levels must contain 4 or fewer entries" } }, "Invalid_Level_Attribute": { "value": { "status": "error", "message": "levels[].attributeId must reference an existing, single-select controlled-vocabulary attribute" } }, "Values_Depth_Exceeded": { "value": { "status": "error", "message": "values nesting depth must not exceed the number of defined levels" } }, "Duplicate_Value_Id": { "value": { "status": "error", "message": "Duplicate id found in the submitted values tree" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "409": { "description": "Conflict — a cascade with the same name (case-insensitive) already exists for this customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "A metadata cascade with this name already exists" } } } } } } }, "/metadata/cascades/{id}": { "get": { "operationId": "GetMetadataCascade", "tags": [ "METADATA CASCADES" ], "summary": "(NEW!) Get Metadata Cascade", "description": "Retrieve a single metadata cascade by its ID. This is the one place in the cascades API where everything is always returned unconditionally — no `include` option, no summary/lightweight mode.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the cascade to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" } } ], "responses": { "200": { "description": "The requested metadata cascade.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-cascade-detail" }, "examples": { "Cascade_Detail": { "summary": "Full cascade detail", "value": { "id": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "name": "Region Cascade", "searchField": "region_cascade", "levels": [ { "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70", "attributeName": "Continent", "order": 0 }, { "attributeId": "c8b6d4f2-1a3e-4c9b-8f7d-3e2a9c5b1d64", "attributeName": "Country", "order": 1 } ], "nameVisible": true, "featured": null, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1771432800000, "lastUpdatedDate": "2026-02-18T16:40:00Z", "usedIn": { "metadataTables": [ { "id": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83", "name": "Store Locations Table" } ], "metadataGroups": [ { "id": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42", "name": "Retail Assets" } ], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] }, "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "North America", "source": null, "children": [ { "id": "7b2e9c4a-3f1d-4e8b-9a6c-5d0f2a7b3e91", "name": "United States", "source": null, "children": [] }, { "id": "1c9a4e7f-6b3d-4a25-8f7c-2e9b5d1a4c63", "name": "Canada", "source": "north_america_countries_cv", "children": [] } ] } ] } } } } } }, "400": { "description": "Bad request — malformed `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "id must be a valid UUID" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no cascade exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No cascade found for the provided id" } } } } } }, "patch": { "operationId": "UpdateMetadataCascade", "tags": [ "METADATA CASCADES" ], "summary": "(NEW!) Update Metadata Cascade", "description": "Update an existing cascade's `name`, `nameVisible`, and/or its full value tree. `levels` and `featured` can never be changed through this endpoint — `levels` because restructuring which attributes back a level could invalidate the existing value tree, and `featured` because it exists specifically to protect a cascade from deletion and would mean nothing if it could simply be toggled off here.\n\n**Business Rules:**\n- At least one of `name`, `nameVisible`, `values` is required.\n- When `values` is provided, it fully replaces the existing tree — nodes omitted from the request are removed. Same depth and duplicate-`id` rules as create.\n- `usedIn` is not enforced or checked on this endpoint — a value may be updated or removed even while referenced on assets; asset reconciliation is handled by a separate downstream process, out of scope here.\n- A new `name` colliding with an existing cascade's `name`/`searchField` is rejected with `409`.\n- An optional `expectedLastUpdatedEpoch` concurrency check protects against clobbering another admin's concurrent edit. If it doesn't match the cascade's current `lastUpdatedEpoch`, the request is rejected with `409` and the response includes `currentLastUpdatedEpoch`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the cascade to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" } } ], "requestBody": { "description": "JSON object updating the cascade. At least one of `name`, `nameVisible`, `values` is required. `levels` and `featured` are never accepted.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-metadata-cascade" }, "examples": { "Update Values": { "summary": "Replace the value tree, with a concurrency check", "value": { "expectedLastUpdatedEpoch": 1771432800000, "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "North America", "children": [ { "id": "7b2e9c4a-3f1d-4e8b-9a6c-5d0f2a7b3e91", "name": "United States", "children": [] }, { "id": "1c9a4e7f-6b3d-4a25-8f7c-2e9b5d1a4c63", "name": "Canada", "children": [] } ] } ] } }, "Rename Cascade": { "summary": "Rename the cascade and hide its name on assets", "value": { "name": "Global Region Cascade", "nameVisible": false } } } } } }, "responses": { "200": { "description": "Updated. Returns the complete cascade detail, mirroring `GET /metadata/cascades/{id}`, reflecting the values tree exactly as it now stands.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-cascade-detail" }, "examples": { "Updated_Cascade": { "summary": "Updated cascade", "value": { "id": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "name": "Global Region Cascade", "searchField": "region_cascade", "levels": [ { "attributeId": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70", "attributeName": "Continent", "order": 0 }, { "attributeId": "c8b6d4f2-1a3e-4c9b-8f7d-3e2a9c5b1d64", "attributeName": "Country", "order": 1 } ], "nameVisible": false, "featured": null, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1770714900000, "createdDate": "2026-02-10T09:15:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1773480000000, "lastUpdatedDate": "2026-09-05T11:20:00Z", "usedIn": { "metadataTables": [], "metadataGroups": [], "metadataTemplates": [] }, "values": [ { "id": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74", "name": "North America", "source": null, "children": [ { "id": "7b2e9c4a-3f1d-4e8b-9a6c-5d0f2a7b3e91", "name": "United States", "source": null, "children": [] }, { "id": "1c9a4e7f-6b3d-4a25-8f7c-2e9b5d1a4c63", "name": "Canada", "source": null, "children": [] } ] } ] } } } } } }, "400": { "description": "Bad request — no updatable field provided, an attempt to set `levels`/`featured`, or `values` nesting/duplicate-`id` violations.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "No_Updatable_Field": { "value": { "status": "error", "message": "At least one of name, nameVisible, values is required" } }, "Levels_Not_Accepted": { "value": { "status": "error", "message": "levels cannot be changed after creation" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no cascade exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No cascade found for the provided id" } } } }, "409": { "description": "Conflict — the new `name` collides with an existing cascade, or `expectedLastUpdatedEpoch` no longer matches the cascade's current `lastUpdatedEpoch`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "currentLastUpdatedEpoch": { "type": "integer", "description": "Present only for a stale-update conflict — the cascade's actual current `lastUpdatedEpoch`." } } }, "examples": { "Name_Collision": { "value": { "message": "A metadata cascade with this name already exists" } }, "Stale_Update": { "value": { "message": "Cascade was modified since expectedLastUpdatedEpoch", "currentLastUpdatedEpoch": 1772000000000 } } } } } } } }, "delete": { "operationId": "DeleteMetadataCascade", "tags": [ "METADATA CASCADES" ], "summary": "(NEW!) Delete Metadata Cascade", "description": "Permanently remove a metadata cascade. Deletion is blocked if the cascade is featured, and blocked if it is still referenced by a table (and, transitively, any template that reaches it through that table).\n\n**Business Rules:**\n- Checks run in this order: not found, then featured, then in-use.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the cascade to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" } } ], "responses": { "204": { "description": "No Content. The cascade has been permanently deleted." }, "400": { "description": "Bad request — malformed `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "id must be a valid UUID" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no cascade exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No cascade found for the provided id" } } } }, "409": { "description": "Conflict — the cascade is featured, or is still referenced by a table (checked in that order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "usedIn": { "type": "object", "description": "Present only for the in-use conflict.", "properties": { "metadataTables": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "examples": { "Featured": { "value": { "message": "Featured cascades cannot be deleted" } }, "In_Use": { "value": { "message": "Cascade is still referenced by 1 table and cannot be deleted", "usedIn": { "metadataTables": [ { "id": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83", "name": "Store Locations Table" } ], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } } } } } } } } }, "/metadata/tables": { "get": { "operationId": "ListMetadataTables", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) List Metadata Tables (Paginated)", "description": "Retrieve a paginated, searchable list of metadata tables for UI consumption. Column detail is excluded to keep this endpoint lightweight; only a count (`fieldCount`) is returned here, with full column detail available via `GET /metadata/tables/{id}`.\n\n**Defaults:**\n- `sortField` defaults to `name`.\n- `order` defaults to `asc`.\n- `from` defaults to `0`.\n- `limit` defaults to `100`, maximum `100`.\n\n**Business Rules:**\n- `searchTerm` is a case-insensitive partial match on table `name`.\n- `inUse` accepts a boolean (`true`/`false` — aggregate: used anywhere at all) or one of `metadataGroups`, `metadataTemplates`, filtering to tables referenced in that specific usage category. Omitted applies no filter. `inUse` and `isSmartTable` are both valid `sortField` values.\n- `isSmartTable` filters to smart or standard tables only; omitted applies no filter.\n- `includeSystem` defaults to `false`. When `true`, also returns read-only, platform-owned tables used internally by various platform functionalities, alongside user-created ones. System tables cannot be edited or deleted by users.\n- `visible` and `tableNameVisible` are excluded entirely from this response — both are dead fields (the admin screen never lets anyone set either to anything but its fixed default).\n- `usedIn` is shaped `{ metadataGroups: [], metadataTemplates: [] }` and never includes an `attributes` category — attributes never reference a table; a table contains attributes as its columns, never the reverse.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive partial match on table name.", "required": false, "schema": { "type": "string" } }, { "name": "inUse", "in": "query", "description": "Filters by usage status. `true`/`false` filters on aggregate usage (referenced anywhere at all). One of `metadataGroups`, `metadataTemplates` filters to tables referenced in that specific usage category. Omitted applies no filter.", "required": false, "schema": { "type": "string", "enum": [ "true", "false", "metadataGroups", "metadataTemplates" ] }, "examples": { "Referenced_In_Groups": { "summary": "GET /metadata/tables?inUse=metadataGroups", "description": "Returns only tables referenced directly in at least one Group.", "value": "metadataGroups" }, "Referenced_In_Templates": { "summary": "GET /metadata/tables?inUse=metadataTemplates", "description": "Returns only tables referenced directly in at least one Template.", "value": "metadataTemplates" } } }, { "name": "isSmartTable", "in": "query", "description": "Filters to smart (`true`) or standard (`false`) tables only. Omitted applies no filter.", "required": false, "schema": { "type": "boolean" } }, { "name": "includeSystem", "in": "query", "description": "When `true`, also returns read-only, platform-owned tables used internally by various platform functionalities, in addition to user-created ones. System tables cannot be edited or deleted by users. Defaults to `false`.", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, maximum `100`.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `name`.", "required": false, "schema": { "type": "string", "enum": [ "name", "createdEpoch", "lastUpdatedEpoch", "inUse", "isSmartTable" ], "default": "name" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Paginated list of metadata tables.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-table-list" }, "examples": { "Metadata_Tables_Page": { "summary": "A page of metadata tables", "value": { "hitCount": 24, "results": [ { "id": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92", "name": "Store Locations Table", "searchField": "store_locations_table", "isSingleRow": false, "isSmartTable": false, "convertTo": null, "featured": null, "fieldCount": 3, "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1772704800000, "createdDate": "2026-03-05T10:00:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1773325200000, "lastUpdatedDate": "2026-03-12T14:20:00Z", "inUse": true, "usedIn": { "metadataGroups": [], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } ] } } } } } }, "400": { "description": "Bad request — invalid query parameters.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField: must be one of name, createdEpoch, lastUpdatedEpoch, inUse, isSmartTable" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } } } }, "post": { "operationId": "CreateMetadataTable", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) Create Metadata Table", "description": "Create a new metadata table in a single call.\n\n**Defaults:**\n- `isSmartTable` defaults to `false`.\n\n**Business Rules:**\n- `tableFields` must contain between 1 and 12 effective columns — a plain or controlled-vocabulary field counts as 1, a cascade field counts as its number of levels. Example: a table with 9 plain fields can add one more cascade only if that cascade has 3 or fewer levels.\n- Each `tableFields[].fieldId` must reference an existing attribute or cascade (never another table); no two entries may reference the same `fieldId`.\n- `isSingleRow` and `isSmartTable` are mutually exclusive and permanently fixed once set.\n- `isSmartTable` is subject to a 25-per-customer smart-table cap, enforced at creation time.\n- A duplicate `name`/`searchField` is rejected with `409`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the table to create. Required: `name`, `isSingleRow`, `tableFields`. Optional: `isSmartTable` (defaults to `false`).", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-metadata-table" }, "examples": { "Create Standard Table": { "summary": "Create a standard table with three columns", "value": { "name": "Store Locations Table", "isSingleRow": false, "isSmartTable": false, "tableFields": [ { "fieldOrder": 1, "fieldId": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61" }, { "fieldOrder": 2, "fieldId": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" }, { "fieldOrder": 3, "fieldId": "f4a92e6d-3c81-4f5a-9d27-6b3e8a1c4f90" } ] } } } } } }, "responses": { "201": { "description": "Created. Same shape as `GET /metadata/tables/{id}`, `usedIn` empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-table-detail" }, "examples": { "Created_Table": { "summary": "Newly created table", "value": { "id": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92", "name": "Store Locations Table", "searchField": "store_locations_table", "isSingleRow": false, "isSmartTable": false, "convertTo": null, "featured": null, "tableFields": [ { "fieldOrder": 1, "fieldId": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61", "fieldName": "Store Name", "fieldType": "textbox" }, { "fieldOrder": 2, "fieldId": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "fieldName": "Region Cascade", "fieldType": "cascade" }, { "fieldOrder": 3, "fieldId": "f4a92e6d-3c81-4f5a-9d27-6b3e8a1c4f90", "fieldName": "Manager Name", "fieldType": "textbox" } ], "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1772704800000, "createdDate": "2026-03-05T10:00:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1772704800000, "lastUpdatedDate": "2026-03-05T10:00:00Z", "usedIn": { "metadataGroups": [], "metadataTemplates": [] } } } } } } }, "400": { "description": "Bad request — missing required field, effective column count exceeds 12, an invalid or duplicate `fieldId`, or both `isSingleRow` and `isSmartTable` set to `true`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Too_Many_Columns": { "value": { "status": "error", "message": "tableFields exceeds the maximum of 12 effective columns" } }, "Invalid_Field_Id": { "value": { "status": "error", "message": "tableFields[].fieldId must reference an existing attribute or cascade" } }, "Duplicate_Field_Id": { "value": { "status": "error", "message": "Duplicate fieldId found in tableFields" } }, "Conflicting_Row_Type": { "value": { "status": "error", "message": "isSingleRow and isSmartTable cannot both be true" } }, "Smart_Table_Cap_Reached": { "value": { "status": "error", "message": "This customer already has the maximum of 25 smart tables" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "409": { "description": "Conflict — a table with the same name (case-insensitive) already exists for this customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "A metadata table with this name already exists" } } } } } } }, "/metadata/tables/{id}": { "get": { "operationId": "GetMetadataTable", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) Get Metadata Table", "description": "Retrieve a single metadata table by its ID, returning the same fields as the list endpoint (minus `fieldCount`) plus the full, flat list of columns (`tableFields`), each denormalized with a type indicator so the UI can render the right control without a second lookup.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the table to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" } } ], "responses": { "200": { "description": "The requested metadata table.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-table-detail" }, "examples": { "Table_Detail": { "summary": "Full table detail", "value": { "id": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92", "name": "Store Locations Table", "searchField": "store_locations_table", "isSingleRow": false, "isSmartTable": false, "convertTo": null, "featured": null, "tableFields": [ { "fieldOrder": 1, "fieldId": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61", "fieldName": "Store Name", "fieldType": "textbox" }, { "fieldOrder": 2, "fieldId": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61", "fieldName": "Region Cascade", "fieldType": "cascade" }, { "fieldOrder": 3, "fieldId": "f4a92e6d-3c81-4f5a-9d27-6b3e8a1c4f90", "fieldName": "Manager Name", "fieldType": "textbox" } ], "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1772704800000, "createdDate": "2026-03-05T10:00:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1773325200000, "lastUpdatedDate": "2026-03-12T14:20:00Z", "usedIn": { "metadataGroups": [], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } } } } } }, "400": { "description": "Bad request — malformed `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "id must be a valid UUID" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no table exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No table found for the provided id" } } } } } }, "patch": { "operationId": "UpdateMetadataTable", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) Update Metadata Table", "description": "Update an existing table's `name` and/or its column list. `searchField`, `isSingleRow`, `isSmartTable`, and `featured` are permanently fixed once set and are never accepted here — `featured` in particular exists specifically to protect a table from deletion; if it could be toggled here, that protection would mean nothing.\n\n**Business Rules:**\n- At least one of `name`, `tableFields` is required.\n- `name` is capped at 32 characters and does not regenerate `searchField`.\n- When `tableFields` is provided, it fully replaces the existing columns — same effective-12-column, valid-reference, and no-duplicate-`fieldId` rules as create.\n- A new `name` colliding with an existing table's `name`/`searchField` is rejected with `409`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the table to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" } } ], "requestBody": { "description": "JSON object updating the table. At least one of `name`, `tableFields` is required. `searchField`, `isSingleRow`, `isSmartTable`, and `featured` are never accepted.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-metadata-table" }, "examples": { "Rename Table": { "summary": "Rename the table", "value": { "name": "Store Locations Table (US)" } }, "Replace Columns": { "summary": "Replace the column list", "value": { "tableFields": [ { "fieldOrder": 1, "fieldId": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61" }, { "fieldOrder": 2, "fieldId": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" }, { "fieldOrder": 3, "fieldId": "f4a92e6d-3c81-4f5a-9d27-6b3e8a1c4f90" }, { "fieldOrder": 4, "fieldId": "c8b6d4f2-1a3e-4c9b-8f7d-3e2a9c5b1d64" } ] } } } } } }, "responses": { "200": { "description": "Updated. Same shape as `GET /metadata/tables/{id}`, `lastUpdated*` refreshed; `createdBy`/`createdEpoch` unchanged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-table-detail" } } } }, "400": { "description": "Bad request — no updatable field provided, an attempt to set `searchField`/`isSingleRow`/`isSmartTable`/`featured`, effective column count exceeds 12, or an invalid/duplicate `fieldId`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "No_Updatable_Field": { "value": { "status": "error", "message": "At least one of name, tableFields is required" } }, "Immutable_Field": { "value": { "status": "error", "message": "isSingleRow cannot be changed after creation" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no table exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No table found for the provided id" } } } }, "409": { "description": "Conflict — the new `name` collides with an existing table's `name`/`searchField`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "A metadata table with this name already exists" } } } } } }, "delete": { "operationId": "DeleteMetadataTable", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) Delete Metadata Table", "description": "Permanently remove a metadata table by its ID. Deletion is blocked if the table is featured, and blocked if it is still referenced by any group or template.\n\n**Business Rules:**\n- Checks run in this order: not found, then featured, then in-use.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the table to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" } } ], "responses": { "204": { "description": "No Content. The table has been permanently deleted." }, "400": { "description": "Bad request — malformed `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "id must be a valid UUID" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no table exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No table found for the provided id" } } } }, "409": { "description": "Conflict — the table is featured, or is still referenced by a group or template (checked in that order).", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "usedIn": { "type": "object", "description": "Present only for the in-use conflict.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "examples": { "Featured": { "value": { "message": "Featured tables cannot be deleted" } }, "In_Use": { "value": { "message": "Table is still referenced by 1 group or template and cannot be deleted", "usedIn": { "metadataGroups": [], "metadataTemplates": [ { "id": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84", "name": "Retail Asset Template" } ] } } } } } } } } } }, "/metadata/tables/{id}/convert-to-smart": { "post": { "operationId": "ConvertMetadataTableToSmart", "tags": [ "METADATA TABLES" ], "summary": "(NEW!) Convert Metadata Table to Smart Table", "description": "Stage a standard table for one-way conversion to a smart table. This endpoint does not perform the search-index remapping migration itself — that happens later, generically, when the admin applies changes in the metadata admin screen. Conversion is irreversible once it completes, which is why it's its own deliberate endpoint rather than something that could happen as a side effect of a routine field update via `PATCH /metadata/tables/{id}`.\n\n**Business Rules:**\n- `isSingleRow` tables cannot be converted.\n- At least one column, directly or via a cascade level, must be facetable.\n- Subject to the same 25-per-customer smart-table cap enforced at creation.\n- A table that's already smart, or already has a conversion pending, is rejected with `409`.\n\nThe user submitting the request must have the **Metadata Template Management** admin privilege.", "parameters": [ { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the table to convert.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" } } ], "responses": { "200": { "description": "Conversion staged. Same shape as `GET /metadata/tables/{id}`, with `convertTo` set to `smart`; `isSmartTable` remains `false` until the reindex completes separately via \"Apply Changes\".", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/metadata-table-detail" }, "examples": { "Conversion_Staged": { "summary": "Standard table staged for conversion to smart", "value": { "id": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92", "name": "Store Locations Table", "searchField": "store_locations_table", "isSingleRow": false, "isSmartTable": false, "convertTo": "smart", "featured": null, "tableFields": [ { "fieldOrder": 1, "fieldId": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61", "fieldName": "Store Name", "fieldType": "textbox" } ], "createdBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "createdEpoch": 1772704800000, "createdDate": "2026-03-05T10:00:00Z", "lastUpdatedBy": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45", "lastUpdatedEpoch": 1773325200000, "lastUpdatedDate": "2026-03-12T14:20:00Z", "usedIn": { "metadataGroups": [], "metadataTemplates": [] } } } } } } }, "400": { "description": "Bad request — `isSingleRow` is `true`, no column is facetable, or the customer's smart-table cap is already reached.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Single_Row_Table": { "value": { "status": "error", "message": "Single-row tables cannot become smart tables" } }, "No_Facetable_Column": { "value": { "status": "error", "message": "At least one column must be facetable to convert to a smart table" } }, "Smart_Table_Cap_Reached": { "value": { "status": "error", "message": "This customer already has the maximum of 25 smart tables" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Metadata Template Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no table exists with the given `id`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No table found for the provided id" } } } }, "409": { "description": "Conflict — the table is already a smart table, or already has a conversion pending.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Already_Smart": { "value": { "status": "error", "message": "This table is already a smart table" } }, "Conversion_Pending": { "value": { "status": "error", "message": "This table already has a conversion pending" } } } } } } } } }, "/request": { "post": { "operationId": "createRequest", "tags": [ "REQUESTS" ], "summary": "Create Request", "description": "Use this endpoint to create a new Request in Tenovos. ", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-request" } } } }, "responses": { "200": { "description": "Created successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-request-2" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/request/{id}": { "patch": { "operationId": "updateRequest", "summary": "Update Request", "description": "Use this endpoint to update an existing Request. Only send the data that you wish to change.", "tags": [ "REQUESTS" ], "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "A Request ID.", "required": true, "style": "simple", "explode": true, "schema": { "type": "string", "format": "uuid", "x-nullable": false, "maxLength": 36, "minLength": 36, "example": "4e428628-2537-40b5-91a4-5393cbf167df" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-request" } } }, "required": true }, "responses": { "204": { "description": "No Content. Successful Update." }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } }, "get": { "operationId": "getRequest", "summary": "Get Request", "description": "Use this endpoint to retrieve a specific request based on the id of the request.", "tags": [ "REQUESTS" ], "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "A Request ID.", "required": true, "style": "simple", "explode": true, "schema": { "type": "string", "format": "uuid", "x-nullable": false, "maxLength": 36, "minLength": 36, "example": "4e428628-2537-40b5-91a4-5393cbf167df" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get-request" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/request/list": { "post": { "operationId": "listRequests", "tags": [ "REQUESTS" ], "summary": "List Requests", "description": "Use this endpoint to return a listing of all Requests. The request body is entirely optional, and by default, the API will return all types of Requests sorted by **created_date** from the most recent to the oldest in batches of 100. \n\nNo metadata on the requests is returned from this endpoint.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-requests" } } }, "required": false }, "responses": { "200": { "description": "Changes applied successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list-requests-2" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/roles": { "get": { "operationId": "getRoles", "tags": [ "SECURITY ROLES" ], "summary": "Retrieve Roles", "description": "Response provides an array of the security Roles that are configured in Tenovos. The items returned are limited to the Roles available to the user making the API call.\n\n**API User credentials must have administrative rights to the User Management privilege.**\n\n**Average Response Time:** 274ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/roles" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/roles/privileges": { "get": { "operationId": "getPrivileges", "tags": [ "SECURITY ROLES" ], "summary": "Retrieve Role Privileges", "description": "Response will include a list of all role privileges available in the system. The user making the request must have the 'Security Template Management' role privilege. All role privileges will be returned by default. User can pass 'enabled' or 'disabled' as a path parameter to return only enabled or disabled role privileges. \nThe user making the request must have **Role Management** privilege. \n\n**Average Response Time:** 188ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-privileges" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/search": { "post": { "operationId": "searchAssets", "tags": [ "SEARCH" ], "summary": "Search Assets", "description": "There are two types of searches available:\n - Simple Keyword Search: Requesting user can get list of Assets against search terms/keywords list. For example [\"keyword1\", \"keyword2\"]\n - Facet Search: Requesting user can get list of Assets against Facet value list. For example [\"Facet: facet_value\"]\n \nSpecifying a value in the 'keywordSearchField' attribute in the request allows you to target keyword searches against Filename, Asset ID, Metadata, or Content (extracted text from documents.\n\nBy default, if not specified in the request, the search operation type will be set to 'AND' for search terms and/or facets. If the 'relevancy' field is passed as true, this will negate the operation selection used\nin legacy search and will leverage the relevancy search matching. When relevancy is set to true, the 'metadataDefinitionSearchField' field within the sortBy object should be set to 'relevance', and the 'order' field should be set to 'desc'.\n\nThe optional 'filters' property accepts an array of facet-style filter attributes and values, using the same `(Attribute Name:\"Value\")` syntax as searchTerm/facet entries. 'filters' entries are applied in addition to any searchTerm entries, and support the '-' prefix to exclude Assets matching a value.\n\nBy default, up to 50 Assets will return from the search. Should you want to limit the amount of assets returned in each response, the value for 'limit' can be set to a number up to 50. You can also set search offset by setting the 'from' property.\nFor example, for the first page, set 'from' to 0. After that set 'from' to 50, 100, 150, etc.\n \nThis endpoint will only return a handful of metadata fields by default. To include more metadata fields in the response, those fields should be included in the 'includes' array. System metadata fields, such as Metadata Template ID, \nshould be entered using camel case (ie, metadataTemplateId). Custom metadata fields should be entered by their attribute search term, prefixed by metadataDocument. For example, to retrieve an attribute called Published Channel, a user \nwould include \"metadataDocument.published_channel\" in the includes array. Fields included in this array will be returned in an object called 'metadataDocument' if those attributes exist on the asset.\n\n**Average Response Time:** 691ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object\n \n ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search-2" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "example": { "status": "error", "message": "Invalid Search Query" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Failed operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/search/collection": { "post": { "operationId": "SearchCollections", "tags": [ "SEARCH" ], "summary": "Search Collections", "description": "Retrieve the collection list against the list of search terms/keywords. By default **AND** operation will be applied between the search terms.\n\nBy default 50 collections will return, you can also set search offset by setting **from** attribute, for example for first page set **from** to zero and after that you set 50, 100, 150 and so on.\n\n**Average Response Time:** 244ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body is a JSON object containing the search terms and search options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" }, "example": { "from": 0, "searchTerm": [ "Pied Piper" ], "includeDeleted": true, "includeVersions": true, "sortBy": [ { "metadataDefinitionSearchField": "lastUpdatedEpoch", "order": "desc" } ], "operation": "ANY", "aggregations": false, "keywordSearchField": "filename" } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object containing the Collection search results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionSearchResult" }, "example": { "hitCount": 2, "totalCount": 2, "result": [ { "collectionId": "7bbef3fa-16a3-474b-af50-267366b18e24", "collectionType": "secured", "collectionDocument": [ "00000000-0000-0000-0000-000000000000", "497fdf9a-8275-4bcf-a287-b74e1911b699", "aac402d1-d760-47f5-ba2b-55365f4289d8" ], "customerId": "1739271540099", "createdEpoch": 1776793585055, "lastUpdatedEpoch": 1776793585055, "name": "Pied Piper Brand Logo Kit", "shared": "N", "shareDocument": [], "userCognitoId": "dc63db1b-1e63-43bc-877e-418931b6895c" }, { "collectionId": "b9f52902-bf5a-4805-bfd9-6422698cd1ef", "collectionType": "secured", "collectionDocument": [ "00000000-0000-0000-0000-000000000000", "a681a00e-0e90-4c5d-99b6-ba3bfbaf3368", "6ac1bb3c-45be-405b-9e77-3770c5f9e808" ], "customerId": "1739271540099", "createdEpoch": 1773683632196, "lastUpdatedEpoch": 1773683632196, "name": "Hooli Generative AI Content", "shared": "N", "shareDocument": [], "userCognitoId": "64848dfa-ce56-4760-ae82-8cd6fab61ac8" } ], "facets": [] } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "example": { "status": "error", "message": "Invalid Search Query" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "returns JSON object with error description.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/search/keyword": { "post": { "operationId": "Search", "tags": [ "SEARCH" ], "summary": "Search Assets by Keyword", "description": "To Retrieve the Assets list there is two types of searches available,\n\n**Simple Keyword Search:** Requesting user can get list of Assets against search terms/keywords list. For example [\"keyword1\", \"keyword2\"]\n\n**Facet Search:** Requesting user can get list of Assets against Facet value list. For example [\"Facet: facet_value\"]\n\n**Targeted Search:** Requesting user can target keyword searches against Filename, Asset ID, Metadata, or Content (extracted text from documents) by passing the optional property of keywordSearchField.\n\nRequesting user can apply the combination of both searches and if there is no keyword/facet in requesting body it will apply wildcard search.\n\nBy default **AND** operation will be applied with search terms and/or facets.\n\n**Filters:** Requesting user can further narrow the result set by passing the optional `filters` property, an array of facet-style filter attributes and values using the same `(Attribute Name:\"Value\")` syntax as searchTerm. `filters` entries are applied in addition to any `searchTerm` entries, and support the `-` prefix to exclude Assets matching a value.\n\nBy default, up to 50 Assets will return from the search.You can also set search offset by setting the **from** property. For example, for the first page, set **from** to zero. After that set **from** to 50, 100, 150, etc.\n\n**Average Response Time:** 4185ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Search" }, "example": { "from": 0, "includeDeleted": false, "includeVersions": false, "searchTerm": [ "(System Security Templates:-\"Full Access\")" ], "filters": [ "(Asset Type:\"Logo\")" ], "sortBy": [ { "metadataDefinitionSearchField": "createdEpoch", "order": "desc" } ], "operation": "AND" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object\n \n ", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResult" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "example": { "status": "error", "message": "Invalid Search Query" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Failed operation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/search/users/{searchText}": { "get": { "operationId": "searchUsersByText", "tags": [ "SEARCH" ], "summary": "Search User Profiles", "description": "Use this endpoint to retrieve a list of User Profiles matching the search keyword provided in the request parameter. Do not enter your search term wrapped in quotation marks.\nProvided keyword will be matched against the user attributes case insensitively - First Name, Last Name, Friendly Name, Username, Email, Phone, Company, Contact, Country, Status, Group Names, and Role Name. Entering \"*\" as your search term will return all users.\nThe response is formatted as an area of objects, with each user account being returned as an object, as well as a key called 'count', which indicates how many accounts met the search critera. A maximum limit of 100 accounts will be returned in the response. \nIn the case that more than 100 accounts meet the search criteria, pagination using the optional 'from' and 'limit' query parameters will be required to retrieve all accounts.\n\n**The user performing this action must have the 'User Management' role privilege.**\n\n**How to use pagination:**\nPagination should be used when the amount of user accounts that match the entered search term exceeds the amount of users (100) returned in a single response. Paginating through the results will require making more than one call to this endpoint.\nTo retrieve the first 100 users, in your query parameters, set your 'from' value to 0, and your 'limit' value to 100. To return the next set of 100 users, leave your 'limit' value as 100, but set your 'from' value to 100. \n\nContinue to repeat this process of adding 100 to your 'from' value until all user account results are captured.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "searchText", "in": "path", "description": "Specify searchText to search across user attributes.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Specify the starting position for the next result set.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Specify the maximum number of records to return each call.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSearchResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/security/template": { "get": { "operationId": "GetSecurityTemplates", "tags": [ "SECURITY TEMPLATES" ], "summary": "Retrieve Security Templates", "description": "User will get the list of Security Templates available to them.\n\nThe user submitting the request must have administrator rights to view Security Templates.\n\nIn response user will get a list, containing template names and their corresponding template id.\n\n**Average Response Time:** 243ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/SecurityTemplate" } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/security/groups": { "get": { "operationId": "GetSecurityGroups", "tags": [ "SECURITY GROUPS" ], "summary": "Retrieve Security Groups", "description": "User will get the list of Security Groups available in the system.\n\nThe user submitting the request must have administrator rights to User Management.\n\nIn response user will get a list, containing group names and their corresponding group id.\n\n**Average Response Time:** 189ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object of Security User Groups and ID's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SecurityGroups" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/security/permissions": { "get": { "operationId": "GetSecurityPermissions", "tags": [ "SECURITY ROLES" ], "summary": "Retrieve Security Permissions", "description": "Response will include a list of all security permissions available in the system. The user making the request must \nhave the **Security Template Management** role privilege.\n\n**Average Response Time:** 231ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object of Security User Groups and ID's.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-permissions" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/security/templates": { "get": { "operationId": "ListSecurityTemplates", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) List Security Templates (Paginated)", "description": "Retrieve an offset-paginated list of security, rights, or access templates for the authenticated customer. Each row is a lightweight summary — group and permission counts, not group contents — suited to an admin browse/list screen.\n\n**Defaults:**\n- `type` defaults to `security-template`.\n- `from` defaults to `0`.\n- `limit` defaults to `100`.\n- `sortField` defaults to `templateName`.\n- `order` defaults to `asc`.\n\n**Business Rules:**\n- `searchTerm` is trimmed and, when non-empty, matched as a case-insensitive substring against template name. It is trimmed before use, so a blank or whitespace-only value is treated as if omitted. Literal `%` and `_` are treated as text, not SQL wildcards.\n- Results are ordered by the requested `sortField`/`order`. Template `id` is used as a deterministic secondary sort field, using the same `order` as the primary sort field.\n- `groupCount` and `permissionCount` are returned as first-class fields without returning the underlying group or permission objects.\n\nThe user submitting the request must have the **Security Template Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive substring match against template name. Trimmed before use — a blank or whitespace-only value is treated as if omitted. Literal `%` and `_` are treated as text, not SQL wildcards. Omitted returns all templates of the requested `type`.", "required": false, "schema": { "type": "string", "example": "confidential" } }, { "name": "type", "in": "query", "description": "Template classification to list. Defaults to `security-template`.", "required": false, "schema": { "type": "string", "enum": [ "security-template", "rights-template", "access-template" ], "default": "security-template" } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `templateName`.", "required": false, "schema": { "type": "string", "enum": [ "templateName", "groupCount", "permissionCount", "createdEpoch", "lastUpdatedEpoch" ], "default": "templateName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } } ], "responses": { "200": { "description": "Paginated list of security templates.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "description": "Templates on this page.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the template.", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" }, "name": { "type": "string", "description": "Display name of the template.", "example": "Confidential" }, "type": { "type": "string", "enum": [ "security-template", "rights-template", "access-template" ], "example": "security-template" }, "groupCount": { "type": "integer", "description": "Total number of groups on the template.", "example": 34 }, "permissionCount": { "type": "integer", "description": "Total number of permissions granted across all groups, including the watermark permission.", "example": 12 }, "createdBy": { "type": "string", "format": "uuid", "description": "User ID of the template's creator.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User ID of the user who last updated the template.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1773070399999 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last updated date.", "example": "2026-03-11T15:00:00Z" } } } }, "pageInfo": { "type": "object", "properties": { "from": { "type": "integer", "description": "Offset of the first result on this page.", "example": 0 }, "limit": { "type": "integer", "description": "Maximum number of results requested per page.", "example": 100 }, "totalCount": { "type": "integer", "description": "Total number of templates matching the query.", "example": 120 }, "hasNextPage": { "type": "boolean", "description": "Whether more templates exist beyond this page.", "example": true } } } } }, "examples": { "Security_Templates_Page": { "summary": "A page of security templates", "value": { "templates": [ { "id": "a9380047-07d7-48aa-b4b7-474d00f0f428", "name": "Confidential", "type": "security-template", "groupCount": 34, "permissionCount": 12, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z" } ], "pageInfo": { "from": 0, "limit": 100, "totalCount": 120, "hasNextPage": true } } } } } } }, "400": { "description": "Bad request — invalid `type`, `from`, `limit`, `sortField`, or `order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Type": { "value": { "message": "Invalid type: must be one of security-template, rights-template, access-template" } }, "Invalid_From": { "value": { "message": "Invalid from: must be a non-negative integer" } }, "Invalid_Limit": { "value": { "message": "Invalid limit: must be a positive integer" } }, "Invalid_Sort_Field": { "value": { "message": "Invalid sortField: must be one of templateName, groupCount, permissionCount, createdEpoch, lastUpdatedEpoch" } }, "Invalid_Order": { "value": { "message": "Invalid order: must be one of asc, desc" } } } } } }, "401": { "description": "Unauthorized. Invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — no token was provided, or the user lacks the Security Template Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Token_Not_Provided": { "value": { "message": "Token not provided" } }, "Insufficient_Privilege": { "value": { "message": "Forbidden" } } } } } } } }, "post": { "operationId": "CreateSecurityTemplate", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) Create Security Template", "description": "Create a security, rights, or access template for the authenticated customer.\n\n\n**Business Rules:**\n- `name` must be trimmed, non-empty, and unique per customer.\n- `type` is set only at creation and is immutable thereafter.\n- Every `groups[].id` and `permissionIds[]` entry must be a well-formed UUID and must exist for the customer (groups) or in the permission catalog (permissions). Unknown ids are rejected with `422`, not silently dropped.\n- Duplicate group ids in the same request are rejected.\n\n**Defaults:**\n- `type` defaults to `security-template`.\n- `groups` defaults to `[]`.\n\nThe response body is returned in the same shape as `GET /security/templates/{id}`, so the UI can render the created template with no follow-up read.\n\nThe user submitting the request must have the **Security Template Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object describing the template to create. Required: `name`. Optional: `type` (defaults to `security-template`), `groups` (defaults to `[]`).", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-security-template" }, "examples": { "Create With Groups": { "summary": "Create a security template with two groups", "value": { "name": "Confidential", "type": "security-template", "groups": [ { "id": "f22dccbc-6032-4279-9f19-d5dc91d9757e", "permissionIds": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ] }, { "id": "dbf4f3d4-fd66-49ec-ad20-dbe3b142a8c9", "permissionIds": [] } ] } }, "Create Empty": { "summary": "Create a template with no groups yet", "value": { "name": "Draft Template" } } } } } }, "responses": { "201": { "description": "Created. The response body is the new template in the same shape as `GET /security/templates/{id}`, including the first page of groups.", "headers": { "Location": { "description": "Path of the newly created template, e.g. `/security/templates/{id}`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-template-detail" }, "examples": { "Created_Template": { "summary": "Newly created security template", "value": { "id": "a9380047-07d7-48aa-b4b7-474d00f0f428", "name": "Confidential", "type": "security-template", "groupCount": 2, "permissionCount": 3, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-09T15:32:35.217Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-09T15:32:35.217Z", "groups": { "totalCount": 2, "items": [ { "id": "f22dccbc-6032-4279-9f19-d5dc91d9757e", "name": "Marketing", "permissions": [ { "id": "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "name": "View", "isPermitted": true } ] } ], "pageInfo": { "hasNextPage": false, "nextCursor": null } } } } } } } }, "400": { "description": "Bad request — missing body, invalid `type`, missing or invalid `name`, malformed group/permission id, or duplicate group id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_Name": { "value": { "message": "name is required" } }, "Name_Too_Long": { "value": { "message": "name must be 75 characters or fewer" } }, "Invalid_Type": { "value": { "message": "Invalid type: must be one of security-template, rights-template, access-template" } }, "Invalid_Group_Id": { "value": { "message": "groups[].id must be a valid UUID" } }, "Duplicate_Group_Id": { "value": { "message": "Duplicate group id: f22dccbc-6032-4279-9f19-d5dc91d9757e" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Security Template Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "409": { "description": "Conflict — a template with this `name` already exists for the customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "existingTemplateId": { "type": "string", "format": "uuid", "description": "ID of the existing template with the conflicting name." } } }, "example": { "message": "A security template with this name already exists", "existingTemplateId": "a9380047-07d7-48aa-b4b7-474d00f0f428" } } } }, "422": { "description": "Unprocessable Entity — a referenced group or permission id does not exist for the customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "invalidGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "invalidPermissionIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "example": { "message": "One or more referenced ids do not exist for this customer", "invalidGroupIds": [ "dbf4f3d4-fd66-49ec-ad20-dbe3b142a8c9" ], "invalidPermissionIds": [] } } } } } } }, "/security/templates/user": { "get": { "operationId": "ListUserSecurityTemplates", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) List Security Templates Available to Current User", "description": "Retrieve the security, rights, or access templates the authenticated user may act on — either templates the user can view, or templates that grant the user a specific permission. Returns only `id` and `name`, suited to populating a template picker for ingest, edit, or delete flows.\n\n**Business Rules:**\n- When `permissionId` is omitted, returns templates the user has view access to (resolved from the user's group membership).\n- When `permissionId` is provided, returns only templates where at least one of the user's groups is granted that permission.\n- Templates with no visible groups, and groups with no remaining permissions after filtering, are excluded.\n\n**Defaults:**\n- `type` defaults to `security-template`.\n- `from` defaults to `0`.\n- `limit` defaults to `100`.\n\nThe requesting user must be authenticated.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "permissionId", "in": "query", "description": "Permission ID to check. When provided, only templates granting this permission to one of the user's groups are returned. When omitted, templates the user can view are returned.", "required": false, "schema": { "type": "string", "format": "uuid", "example": "31bdde6b-1a2c-4d5e-8f90-1234567890ab" } }, { "name": "type", "in": "query", "description": "Template classification to list. Defaults to `security-template`.", "required": false, "schema": { "type": "string", "enum": [ "security-template", "rights-template", "access-template" ], "default": "security-template" } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Must be an integer of `0` or greater; a negative or non-integer value is rejected with a `400`. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "minimum": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to 100.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor for pagination. Omit on the first request. Use the `nextCursor` value from the previous response for subsequent pages.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Templates the current user may act on.", "content": { "application/json": { "schema": { "type": "object", "properties": { "templates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" }, "name": { "type": "string", "example": "Confidential" } } } }, "pageInfo": { "type": "object", "properties": { "hasNextPage": { "type": "boolean" }, "nextCursor": { "type": "string", "nullable": true } } } } }, "examples": { "User_Templates": { "summary": "Templates the current user can use", "value": { "templates": [ { "id": "a9380047-07d7-48aa-b4b7-474d00f0f428", "name": "Confidential" } ], "pageInfo": { "hasNextPage": false, "nextCursor": null } } } } } } }, "400": { "description": "Bad request — invalid `type`, malformed `cursor`, invalid `limit`, or malformed `permissionId`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Invalid_Permission_Id": { "value": { "message": "permissionId must be a valid UUID" } }, "Invalid_Type": { "value": { "message": "Invalid type: must be one of security-template, rights-template, access-template" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/security/templates/{templateId}": { "get": { "operationId": "GetSecurityTemplate", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) Get Security Template", "description": "Retrieve full detail for a single security, rights, or access template — header fields plus a paginated page of its groups, each with its permissions.\n\n**Defaults:**\n- `includePermissions` defaults to `true`.\n- `groupLimit` defaults to `100`.\n\n**Pagination:**\n- Loop on `groups.pageInfo.nextCursor`, passing it back as `groupCursor`, until `groups.pageInfo.hasNextPage` is `false`.\n\nThe user submitting the request must have the **Security Template Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "description": "The unique ID of the security template.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" } }, { "name": "includePermissions", "in": "query", "description": "When `true`, each group includes its `permissions` array. Defaults to `true`.", "required": false, "schema": { "type": "boolean", "default": true } }, { "name": "groupLimit", "in": "query", "description": "Number of groups to return per page. Defaults to 100.", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "groupCursor", "in": "query", "description": "Opaque cursor for paging the template's groups. Omit on the first request. Use `groups.pageInfo.nextCursor` from the previous response for subsequent pages.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Full detail of the security template.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-template-detail" }, "examples": { "Template_Detail": { "summary": "Full detail with one page of groups", "value": { "id": "a9380047-07d7-48aa-b4b7-474d00f0f428", "name": "Confidential", "type": "security-template", "groupCount": 34, "permissionCount": 12, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-11T14:32:35Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070399999, "lastUpdatedDate": "2026-03-11T15:00:00Z", "groups": { "totalCount": 34, "items": [ { "id": "f22dccbc-6032-4279-9f19-d5dc91d9757e", "name": "Marketing", "permissions": [ { "id": "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "name": "View", "isPermitted": true } ] } ], "pageInfo": { "hasNextPage": true, "nextCursor": "eyJpZCI6ImYyMmRjY2JjIn0" } } } } } } } }, "400": { "description": "Bad request — malformed `groupCursor` or invalid `groupLimit`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Malformed cursor" } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Security Template Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no security template exists for the provided ID.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Security template not found" } } } } } }, "patch": { "operationId": "UpdateSecurityTemplate", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) Update Security Template", "description": "Partially update a security, rights, or access template. Only the fields present in the body are changed.\n\n**Business Rules:**\n- `type` is not an updatable field. If present in the body, the request is rejected with `400`. Type is fixed at creation because assets and metadata templates reference the template by id and assume its type.\n- At least one of `name` or `groups` must be present, or the request is rejected with `400`. Unknown fields are also rejected with `400`.\n- When `groups` is present, it is a full replacement of the template's group/permission set — omitted groups are removed, not left alone.\n- Every `groups[].id` and `permissionIds[]` entry must be a well-formed UUID and must exist for the customer (groups) or in the permission catalog (permissions). Unknown ids are rejected with `422`.\n- `name`, if changed, is re-checked for uniqueness per customer.\n\n**Optimistic Concurrency:**\n- Opt-in via `expectedLastUpdatedEpoch`. If provided, it is compared against the template's current `lastUpdatedEpoch`; a mismatch is rejected with `409` and `code: STALE_UPDATE`. If omitted, the update proceeds last-write-wins.\n\nThe response body is returned in the same shape as `GET /security/templates/{id}`.\n\nThe user submitting the request must have the **Security Template Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "templateId", "in": "path", "description": "The unique ID of the security template to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" } } ], "requestBody": { "description": "JSON object with the fields to change. `name` and/or `groups` — at least one required. `groups`, when present, fully replaces the existing group/permission set. `type` cannot be included.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-security-template" }, "examples": { "Rename Only": { "summary": "Update only the name", "value": { "name": "Confidential - Marketing" } }, "Replace Groups": { "summary": "Replace the full group/permission set with a concurrency check", "value": { "groups": [ { "id": "f22dccbc-6032-4279-9f19-d5dc91d9757e", "permissionIds": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ] } ], "expectedLastUpdatedEpoch": 1773070399999 } } } } } }, "responses": { "200": { "description": "Updated. The response body is the template in the same shape as `GET /security/templates/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-template-detail" }, "examples": { "Updated_Template": { "summary": "Template after update", "value": { "id": "a9380047-07d7-48aa-b4b7-474d00f0f428", "name": "Confidential - Marketing", "type": "security-template", "groupCount": 1, "permissionCount": 1, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-09T15:32:35.217Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070500000, "lastUpdatedDate": "2026-03-09T15:35:00.000Z", "groups": { "totalCount": 1, "items": [ { "id": "f22dccbc-6032-4279-9f19-d5dc91d9757e", "name": "Marketing", "permissions": [ { "id": "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "name": "View", "isPermitted": true } ] } ], "pageInfo": { "hasNextPage": false, "nextCursor": null } } } } } } } }, "400": { "description": "Bad request — no updatable fields, unknown field, `type` present, invalid `name`, or malformed group/permission id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "No_Updatable_Fields": { "value": { "message": "At least one of name or groups must be provided" } }, "Type_Not_Updatable": { "value": { "message": "type cannot be changed after creation" } }, "Unknown_Field": { "value": { "message": "Unexpected field [customerId] in security template update payload" } }, "Name_Too_Long": { "value": { "message": "name must be 75 characters or fewer" } }, "Invalid_Group_Id": { "value": { "message": "groups[].id must be a valid UUID" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Security Template Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no security template exists for this id and customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Security template not found" } } } }, "409": { "description": "Conflict — either the new `name` collides with an existing template, or `expectedLastUpdatedEpoch` no longer matches (a concurrent update won). Distinguish using `code`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "NAME_CONFLICT", "STALE_UPDATE" ] }, "existingTemplateId": { "type": "string", "format": "uuid", "description": "Present only when `code` is `NAME_CONFLICT`." } } }, "examples": { "Name_Conflict": { "value": { "message": "A security template with this name already exists", "code": "NAME_CONFLICT", "existingTemplateId": "6a0e6a1b-6a6a-4c8d-9f0e-6a6a6a6a6a6a" } }, "Stale_Update": { "value": { "message": "Template was modified by another request", "code": "STALE_UPDATE" } } } } } }, "422": { "description": "Unprocessable Entity — a referenced group or permission id does not exist for the customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "invalidGroupIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "invalidPermissionIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } }, "example": { "message": "One or more referenced ids do not exist for this customer", "invalidGroupIds": [], "invalidPermissionIds": [ "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ] } } } } } }, "delete": { "operationId": "DeleteSecurityTemplate", "tags": [ "SECURITY TEMPLATES" ], "summary": "(NEW!) Delete Security Template", "description": "Permanently delete a security, rights, or access template the authenticated customer owns.\n\n**Delete Rules:**\n- Template must exist for the authenticated customer.\n- Deletion is blocked when the template is still referenced: either it has stored dependencies, or it is applied somewhere — for `access-template`, the count of metadata templates using it; otherwise, the count of assets using it.\n- There is no force-delete option. An in-use template can only be removed directly against the database, outside this API.\n- On success, the deletion is recorded in `tenovos_delete_history` for the `security-template` type.\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **Security Template Management** admin privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "templateId", "in": "path", "description": "The unique ID of the security template to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" } } ], "responses": { "204": { "description": "No Content. The security template has been permanently deleted." }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks Security Template Management admin privilege.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } }, "404": { "description": "Not found — no security template exists for this id and customer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Security template not found" } } } }, "409": { "description": "Conflict — the template is in use and cannot be deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" }, "code": { "type": "string", "enum": [ "TEMPLATE_IN_USE" ] }, "usageCount": { "type": "integer", "description": "Number of objects referencing this template." }, "usageType": { "type": "string", "enum": [ "asset", "metadata-template" ], "description": "What kind of object the usage count reflects. `metadata-template` for access templates; `asset` otherwise." }, "dependencies": { "type": "array", "description": "Stored dependency references, when present.", "items": { "type": "object" } } } }, "example": { "message": "Security template is in use and cannot be deleted", "code": "TEMPLATE_IN_USE", "usageCount": 42, "usageType": "asset", "dependencies": [] } } } } } } }, "/security/roles": { "get": { "operationId": "ListSecurityRoles", "tags": [ "SECURITY ROLES" ], "summary": "(NEW!) List Security Roles (Paginated)", "description": "Retrieve a paginated, searchable list of the security roles configured for the authenticated customer.\n\n**Defaults:**\n- `sortField` defaults to `roleName`.\n- `order` defaults to `asc`.\n- `from` defaults to `0`.\n- `limit` defaults to `100` (clamped to `100` if a higher value is supplied).\n\n**Business Rules:**\n- `searchTerm` is a case-insensitive substring match on role name. Special LIKE characters (`%`, `_`, `\\`) are treated as literal text, not wildcards.\n- `consentForm` is not included on list items — it only appears on the get-by-id detail.\n\nThe user submitting the request must have the **Role Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive substring match on role name. Special LIKE characters (`%`, `_`, `\\`) are treated as literal text.", "required": false, "schema": { "type": "string" } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `roleName`.", "required": false, "schema": { "type": "string", "enum": [ "roleName", "privilegeCount", "userCount", "createdEpoch", "lastUpdatedEpoch" ], "default": "roleName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, maximum `100` (values above `100` are silently clamped).", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } } ], "responses": { "200": { "description": "Paginated list of security roles.", "content": { "application/json": { "schema": { "type": "object", "properties": { "roles": { "type": "array", "description": "Roles on this page.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the role.", "example": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" }, "name": { "type": "string", "description": "Display name of the role.", "example": "Creative Producer" }, "privilegeCount": { "type": "integer", "description": "Number of privileges granted to the role.", "example": 2 }, "userCount": { "type": "integer", "description": "Number of users currently assigned this role.", "example": 12 }, "createdBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the role's creator.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1734000000000 }, "createdDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date.", "example": "2024-12-12T12:00:00.000Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the last user to update the role.", "example": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1755600000000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last-updated date.", "example": "2025-08-19T12:00:00.000Z" } } } }, "pageInfo": { "type": "object", "properties": { "from": { "type": "integer", "description": "Offset of the first result on this page." }, "limit": { "type": "integer", "description": "Maximum number of results requested per page." }, "total": { "type": "integer", "description": "Total number of roles matching the query." }, "hasNextPage": { "type": "boolean", "description": "Whether more roles exist beyond this page (`from + < total`)." } } } } }, "examples": { "Security_Roles_Page": { "summary": "A page of security roles", "value": { "roles": [ { "id": "6c15af83-d4a9-4772-875a-1c8a2bb1688f", "name": "Creative Producer", "privilegeCount": 3, "userCount": 12, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" } ], "pageInfo": { "from": 0, "limit": 100, "total": 1, "hasNextPage": false } } } } } } }, "400": { "description": "Bad request — invalid `sortField`, `order`, `from`, or `limit`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField: must be one of roleName, privilegeCount, userCount, createdEpoch, lastUpdatedEpoch" } }, "Invalid_From": { "value": { "status": "error", "message": "from must be an integer greater than or equal to 0" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Role Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } } } }, "post": { "operationId": "CreateSecurityRole", "tags": [ "SECURITY ROLES" ], "summary": "(NEW!) Create Security Role", "description": "Create a security role for the authenticated customer.\n\n**Business Rules:**\n- `name` must be 1-32 characters after trimming, and unique per customer, case-insensitively — enforced by a database constraint, so a race between two concurrent creates for the same name always resolves to exactly one winner and a `409` for the loser.\n- Any field not in `{name, consentForm, privileges}` is rejected with `400`.\n\n**Defaults:**\n- `consentForm` defaults to `\"\"`. `null` is treated as absent.\n- `privileges` defaults to `[]`. Entries are de-duplicated case-insensitively.\n\n**Validation:**\n- Each `privileges` entry must be a syntactically valid UUID (`400` if not), then must exist and be enabled in the customer's privilege catalog (`422` if any id is unknown or disabled).\n\nThe user submitting the request must have the **Role Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the role to create. Required: `name`. Optional: `consentForm` (defaults to `\"\"`), `privileges` (defaults to `[]`).", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-security-role" }, "examples": { "Create With Privileges": { "summary": "Create a role with an initial privilege", "value": { "name": "Compression Engineer", "consentForm": "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm and follow all platform security policies.", "privileges": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ] } }, "Create Empty": { "summary": "Create a role with no privileges yet", "value": { "name": "Draft Role" } } } } } }, "responses": { "201": { "description": "Created. The response body is the new role in the same shape as `GET /security/roles/{id}` — a brand-new role always has `userCount: 0` and `usedIn.presets: []`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-role-detail" }, "examples": { "Created_Role": { "summary": "Newly created security role", "value": { "id": "7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "name": "Compression Engineer", "consentForm": "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm and follow all platform security policies.", "privilegeCount": 1, "privileges": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ], "userCount": 0, "usedIn": { "presets": [] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-09T15:32:35.217Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-09T15:32:35.217Z" } } } } } }, "400": { "description": "Bad request — missing/oversized `name`, bad field type, a non-UUID privilege id, `privileges` not an array, or an unexpected field.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Missing_Name": { "value": { "status": "error", "message": "name is required" } }, "Name_Too_Long": { "value": { "status": "error", "message": "name must be 32 characters or fewer" } }, "Invalid_Privilege_Id": { "value": { "status": "error", "message": "privileges[].id must be a valid UUID" } }, "Unexpected_Field": { "value": { "status": "error", "message": "Unexpected field: type" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Role Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "409": { "description": "Conflict — a role with the same name (case-insensitive) already exists for this customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "DUPLICATE_ROLE_NAME" ] }, "details": { "type": "object", "properties": { "existingRoleId": { "type": "string", "format": "uuid" } } } } }, "example": { "status": "error", "message": "A security role with this name already exists", "code": "DUPLICATE_ROLE_NAME", "details": { "existingRoleId": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" } } } } }, "422": { "description": "Unprocessable Entity — one or more privilege ids don't exist or are disabled for this customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNKNOWN_REFERENCES" ] }, "details": { "type": "object", "properties": { "missingPrivilegeIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "example": { "status": "error", "message": "One or more referenced privileges do not exist for this customer", "code": "UNKNOWN_REFERENCES", "details": { "missingPrivilegeIds": [ "c1a2b3d4-5e6f-7890-abcd-ef1234567890" ] } } } } } } } }, "/security/roles/{id}": { "get": { "operationId": "GetSecurityRole", "tags": [ "SECURITY ROLES" ], "summary": "(NEW!) Get Security Role", "description": "Retrieve the full detail of a single security role, including its consent form, granted privileges, and everywhere it's currently referenced.\n\nThe user submitting the request must have the **Role Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the role. Opaque string, not necessarily a UUID.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" } } ], "responses": { "200": { "description": "Full detail of the security role.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-role-detail" }, "examples": { "Creative_Producer": { "summary": "A role with two privileges, in use by 12 users and one preset", "value": { "id": "6c15af83-d4a9-4772-875a-1c8a2bb1688f", "name": "Creative Producer", "consentForm": "By accepting this role you agree to uphold Pied Piper's brand and confidentiality guidelines when producing creative assets.", "privilegeCount": 2, "privileges": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ], "userCount": 12, "usedIn": { "presets": [ { "id": "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f", "name": "Pied Piper Marketing Upload", "type": "upload" } ] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Role Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no role exists for the provided ID and customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Role not found" } } } } } }, "patch": { "operationId": "UpdateSecurityRole", "tags": [ "SECURITY ROLES" ], "summary": "(NEW!) Update Security Role", "description": "Partially update a security role. Only the fields present in the body are changed.\n\n**Business Rules:**\n- At least one of `name`, `consentForm`, or `privileges` must be present — a body with only `expectedLastUpdatedEpoch`, or an empty object, is rejected with `400`.\n- `privileges`, if supplied, fully replaces the existing set — it is not merged. An empty array clears all privileges. Omitting `privileges` never disturbs the stored role document.\n- Renaming to the role's own current name (even differing only by case) is not a collision.\n\n**Optimistic Concurrency:**\n- `expectedLastUpdatedEpoch` is optional. If supplied and it doesn't match the role's current `lastUpdatedEpoch`, the write is rejected with `409` and `code: STALE_UPDATE`.\n\nThe response body is returned in the same shape as `GET /security/roles/{id}`.\n\nThe user submitting the request must have the **Role Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the role to update.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" } } ], "requestBody": { "description": "JSON object with the fields to change. At least one of `name`, `consentForm`, or `privileges` is required.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-security-role" }, "examples": { "Rename Only": { "summary": "Update only the name", "value": { "name": "Senior Compression Engineer" } }, "Replace Privileges": { "summary": "Replace the full privilege set with a concurrency check", "value": { "privileges": [ "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ], "expectedLastUpdatedEpoch": 1755600000000 } } } } } }, "responses": { "200": { "description": "Updated. The response body is the role in the same shape as `GET /security/roles/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-role-detail" }, "examples": { "Updated_Role": { "summary": "Role after update", "value": { "id": "6c15af83-d4a9-4772-875a-1c8a2bb1688f", "name": "Senior Compression Engineer", "consentForm": "By accepting this role you agree to uphold Pied Piper's brand and confidentiality guidelines when producing creative assets.", "privilegeCount": 1, "privileges": [ "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ], "userCount": 12, "usedIn": { "presets": [ { "id": "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f", "name": "Pied Piper Marketing Upload", "type": "upload" } ] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600500000, "lastUpdatedDate": "2025-08-19T12:08:20.000Z" } } } } } }, "400": { "description": "Bad request — no updatable field present, unexpected field, or invalid field value.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "No_Updatable_Fields": { "value": { "status": "error", "message": "At least one of name, consentForm, or privileges must be provided" } }, "Name_Too_Long": { "value": { "status": "error", "message": "name must be 32 characters or fewer" } }, "Invalid_Privilege_Id": { "value": { "status": "error", "message": "privileges[].id must be a valid UUID" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Role Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no role exists for the provided ID and customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Role not found" } } } }, "409": { "description": "Conflict — either the new `name` collides with an existing role, or `expectedLastUpdatedEpoch` no longer matches. Distinguish using `code`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "DUPLICATE_ROLE_NAME", "STALE_UPDATE" ] }, "details": { "type": "object", "description": "Present only when `code` is `DUPLICATE_ROLE_NAME`.", "properties": { "existingRoleId": { "type": "string", "format": "uuid" } } } } }, "examples": { "Duplicate_Role_Name": { "value": { "status": "error", "message": "A security role with this name already exists", "code": "DUPLICATE_ROLE_NAME", "details": { "existingRoleId": "7d8e9f0a-1b2c-3d4e-5f6a-7b8c9d0e1f2a" } } }, "Stale_Update": { "value": { "status": "error", "message": "Role was modified by another request", "code": "STALE_UPDATE" } } } } } }, "422": { "description": "Unprocessable Entity — one or more privilege ids don't exist or are disabled for this customer. Only checked when `privileges` is part of the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "UNKNOWN_REFERENCES" ] }, "details": { "type": "object", "properties": { "missingPrivilegeIds": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } }, "example": { "status": "error", "message": "One or more referenced privileges do not exist for this customer", "code": "UNKNOWN_REFERENCES", "details": { "missingPrivilegeIds": [ "c1a2b3d4-5e6f-7890-abcd-ef1234567890" ] } } } } } } }, "delete": { "operationId": "DeleteSecurityRole", "tags": [ "SECURITY ROLES" ], "summary": "(NEW!) Delete Security Role", "description": "Permanently delete a security role the authenticated customer owns. There is no force-delete override.\n\n**Delete Rules:**\n- Role must exist for the authenticated customer.\n- Deletion is blocked when either at least one user is currently assigned the role, or at least one preset (upload or filter) still references it in its `role_ids`. Both conditions are checked and reported together — the response names every blocker at once, not just the first one found.\n- The role is not silently unassigned from users or stripped out of presets to allow the delete — the caller must resolve the blockers first.\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **Role Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the role to delete.", "required": true, "schema": { "type": "string", "format": "uuid", "example": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" } } ], "responses": { "204": { "description": "No Content. The role has been permanently deleted." }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the Role Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no role exists for the provided ID and customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Role not found" } } } }, "409": { "description": "Conflict — the role is in use and cannot be deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "ROLE_IN_USE" ] }, "details": { "type": "object", "properties": { "userCount": { "type": "integer", "description": "Number of users currently assigned this role." }, "presets": { "type": "array", "description": "Upload or filter presets still referencing this role.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "upload", "filter" ] } } } } } } } }, "example": { "status": "error", "message": "Role is in use and cannot be deleted", "code": "ROLE_IN_USE", "details": { "userCount": 12, "presets": [ { "id": "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f", "name": "Pied Piper Marketing Upload", "type": "upload" } ] } } } } } } } }, "/security/user-groups": { "get": { "operationId": "ListSecurityUserGroups", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) List Security User Groups (Paginated)", "description": "Retrieve a paginated, searchable list of the security user groups configured for the authenticated customer. This endpoint only ever operates on `type: security` groups — there is no way to request `channel` groups through it.\n\n**Defaults:**\n- `sortField` defaults to `groupName`.\n- `order` defaults to `asc`.\n- `from` defaults to `0`.\n- `limit` defaults to `100` (clamped to `100` if a higher value is supplied).\n\n**Business Rules:**\n- `searchTerm` is a case-insensitive substring match on group name. Special LIKE characters (`%`, `_`, `\\`) are treated as literal text, not wildcards.\n- There is no `type` query parameter. Every group returned is `type: security`. Sending a `type` parameter of any value — including `security` — is rejected with `400`; it is not silently ignored, and it never changes what's returned. Channel groups are created and managed exclusively by the Publishing flow under a separate privilege, never through this API.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive substring match on group name. Special LIKE characters (`%`, `_`, `\\`) are treated as literal text.", "required": false, "schema": { "type": "string" } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `groupName`.", "required": false, "schema": { "type": "string", "enum": [ "groupName", "userCount", "createdEpoch", "lastUpdatedEpoch" ], "default": "groupName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `asc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "asc" } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, maximum `100` (values above `100` are silently clamped).", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } } ], "responses": { "200": { "description": "Paginated list of security user groups.", "content": { "application/json": { "schema": { "type": "object", "properties": { "groups": { "type": "array", "description": "Groups on this page.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the group.", "example": "group-hooli-corporate" }, "name": { "type": "string", "description": "Display name of the group.", "example": "Hooli Corporate" }, "type": { "type": "string", "enum": [ "security" ], "example": "security" }, "userCount": { "type": "integer", "description": "Number of users currently in this group.", "example": 24 }, "createdBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the group's creator.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1734000000000 }, "createdDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date.", "example": "2024-12-12T12:00:00.000Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the last user to update the group.", "example": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1755600000000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last-updated date.", "example": "2025-08-19T12:00:00.000Z" } } } }, "pageInfo": { "type": "object", "properties": { "from": { "type": "integer", "description": "Offset of the first result on this page." }, "limit": { "type": "integer", "description": "Maximum number of results requested per page." }, "total": { "type": "integer", "description": "Total number of groups matching the query." }, "hasNextPage": { "type": "boolean", "description": "Whether more groups exist beyond this page (`from + < total`)." } } } } }, "examples": { "Security_User_Groups_Page": { "summary": "A page of security user groups", "value": { "groups": [ { "id": "group-hooli-corporate", "name": "Hooli Corporate", "type": "security", "userCount": 24, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" } ], "pageInfo": { "from": 0, "limit": 100, "total": 1, "hasNextPage": false } } } } } } }, "400": { "description": "Bad request — invalid `sortField`, `order`, `from`, `limit`, or a `type` parameter was supplied.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Unexpected_Type_Parameter": { "value": { "status": "error", "message": "Unexpected parameter: type" } }, "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField: must be one of groupName, userCount, createdEpoch, lastUpdatedEpoch" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } } } }, "post": { "operationId": "CreateSecurityUserGroup", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) Create Security User Group", "description": "Create a security user group for the authenticated customer. `name` is the only accepted field.\n\n**Business Rules:**\n- `name` must be 1-255 characters after trimming, and unique per customer, case-insensitively — enforced by a database constraint, so a race between two concurrent creates for the same name always resolves to exactly one winner and a `409` for the loser.\n- `type` is not an accepted input field at all. Sending it, with any value, is rejected with `400` — the created group is always `type: security`; this is reflected in the response but can never be set by the caller.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object defining the group to create. `name` is the only accepted field.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create-security-user-group" }, "examples": { "Create Group": { "summary": "Create a new security user group", "value": { "name": "Pied Piper Engineering" } } } } } }, "responses": { "201": { "description": "Created. The response body is the new group in the same shape as `GET /security/user-groups/{id}` — a brand-new group always has `userCount: 0` and `usedIn.securityTemplates: []`.", "headers": { "Location": { "description": "Path of the newly created group, e.g. `/security/user-groups/{id}`.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-user-group-detail" }, "examples": { "Created_Group": { "summary": "Newly created security user group", "value": { "id": "group-pied-piper-engineering", "name": "Pied Piper Engineering", "type": "security", "userCount": 0, "usedIn": { "securityTemplates": [] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1773070355217, "createdDate": "2026-03-09T15:32:35.217Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-09T15:32:35.217Z" } } } } } }, "400": { "description": "Bad request — missing/blank/oversized `name`, or an unexpected field (including `type`).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Missing_Name": { "value": { "status": "error", "message": "name is required" } }, "Name_Too_Long": { "value": { "status": "error", "message": "name must be 255 characters or fewer" } }, "Unexpected_Type_Field": { "value": { "status": "error", "message": "Unexpected field: type" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "409": { "description": "Conflict — a group with the same name (case-insensitive) already exists for this customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "DUPLICATE_GROUP_NAME" ] }, "details": { "type": "object", "properties": { "existingGroupId": { "type": "string" } } } } }, "example": { "status": "error", "message": "A security user group with the same name already exists", "code": "DUPLICATE_GROUP_NAME", "details": { "existingGroupId": "group-hooli-corporate" } } } } } } } }, "/security/user-groups/bulk": { "post": { "operationId": "BulkCreateSecurityUserGroups", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) Bulk Create Security User Groups", "description": "Create multiple security user groups for the authenticated customer in a single all-or-nothing batch. Either every name in the batch is created, or none are — there is no partial success.\n\n**Business Rules:**\n- `names` must be a non-empty array of strings, maximum 50 entries per request. A batch over 50 names is rejected outright with a plain `400` (`\"maximum 50 user groups are allowed in a request\"`) without itemizing individual names — this structural check runs before any per-name validation.\n- Each name follows the same rules as single-create (1-255 characters after trim).\n- A name repeated within the same request (case-insensitively, after trimming) is rejected — it is not silently de-duplicated.\n- All entries in one batch share the same `createdEpoch`/`createdBy` (one request, one actor, one timestamp), and each gets its own id.\n- There is no `Location` response header on this endpoint, since it creates multiple resources.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object listing the group names to create. Required: `names` — non-empty array, maximum 50 entries.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bulk-create-security-user-groups" }, "examples": { "Create Regional Groups": { "summary": "Create three groups in one batch", "value": { "names": [ "Hooli Corporate", "Hooli EMEA", "Hooli APAC" ] } } } } } }, "responses": { "201": { "description": "Created. Every entry in `created` is the full detail shape from `GET /security/user-groups/{id}`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "created": { "type": "array", "items": { "$ref": "#/components/schemas/security-user-group-detail" } } } }, "examples": { "Created_Groups": { "summary": "Three groups created in one batch", "value": { "created": [ { "id": "group-hooli-corporate", "name": "Hooli Corporate", "type": "security", "userCount": 0, "usedIn": { "securityTemplates": [] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1755600000000, "createdDate": "2025-08-19T12:00:00.000Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" }, { "id": "group-hooli-emea", "name": "Hooli EMEA", "type": "security", "userCount": 0, "usedIn": { "securityTemplates": [] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1755600000000, "createdDate": "2025-08-19T12:00:00.000Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" }, { "id": "group-hooli-apac", "name": "Hooli APAC", "type": "security", "userCount": 0, "usedIn": { "securityTemplates": [] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1755600000000, "createdDate": "2025-08-19T12:00:00.000Z", "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" } ] } } } } } }, "400": { "description": "Nothing created. Either the batch exceeds 50 names (plain message, no itemized errors), or one or more names failed validation (`code: VALIDATION_ERROR`, with an itemized `details.errors` array).", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "VALIDATION_ERROR" ] }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "The offending name as submitted." }, "reason": { "type": "string", "enum": [ "invalid", "too_long", "duplicate" ], "description": "`invalid` (missing/blank/not a string), `too_long`, or `duplicate` repeated within the request. A name that duplicates an *existing* group is reported as a `409` instead — see below." }, "message": { "type": "string" } } } } } } } }, "examples": { "Batch_Too_Large": { "summary": "Structural check — over 50 names, rejected before any per-name validation", "value": { "status": "error", "message": "maximum 50 user groups are allowed in a request" } }, "Validation_Errors": { "summary": "One or more names failed per-name validation", "value": { "status": "error", "message": "One or more group names failed validation", "code": "VALIDATION_ERROR", "details": { "errors": [ { "name": " ", "reason": "invalid", "message": "name is required" }, { "name": "Hooli APAC Regional Office of Compression Engineering and Middle-Out Algorithm Research", "reason": "too_long", "message": "Invalid value for [name]. Maximum allowed value is [255]." }, { "name": "hooli apac", "reason": "duplicate", "message": "Duplicate name in request" } ] } } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "409": { "description": "Conflict — nothing created. At least one submitted name already exists for the customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "DUPLICATE_GROUP_NAME" ] }, "details": { "type": "object", "properties": { "errors": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "reason": { "type": "string", "enum": [ "duplicate" ] }, "message": { "type": "string" } } } } } } } }, "example": { "status": "error", "message": "A security user group with the same name already exists", "code": "DUPLICATE_GROUP_NAME", "details": { "errors": [ { "name": "Hooli Corporate", "reason": "duplicate", "message": "A security user group with the same name already exists" } ] } } } } } } } }, "/security/user-groups/{id}": { "get": { "operationId": "GetSecurityUserGroup", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) Get Security User Group", "description": "Retrieve the full detail of a single security user group, including everywhere it's currently referenced.\n\n**Business Rules:**\n- Returns `404` if the group doesn't exist for the caller's customer, or if it exists but is `type: channel` — both cases are indistinguishable to the caller.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the group. Opaque string — not a UUID format requirement, though ids are generated as UUIDs.", "required": true, "schema": { "type": "string", "example": "group-hooli-corporate" } } ], "responses": { "200": { "description": "Full detail of the security user group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-user-group-detail" }, "examples": { "Hooli_Corporate": { "summary": "A group of 24 users, referenced by one security template", "value": { "id": "group-hooli-corporate", "name": "Hooli Corporate", "type": "security", "userCount": 24, "usedIn": { "securityTemplates": [ { "id": "tmpl-hooli-apac-viewers", "name": "Hooli APAC Viewers" } ] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600000000, "lastUpdatedDate": "2025-08-19T12:00:00.000Z" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no group exists for the provided ID and customer, or it exists but is a `channel`-type group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Security user group not found" } } } } } }, "patch": { "operationId": "UpdateSecurityUserGroup", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) Rename Security User Group", "description": "Rename a security user group. `name` is the only editable field on a group — unlike a role's `PATCH`, `name` is always required here, not \"at least one of several fields.\"\n\n**Business Rules:**\n- `type` is not an accepted field here either — rejected with `400`.\n- Caller identity is resolved first (`401` if it can't be), then the group's existence is checked (`404`), then the concurrency guard (if supplied), then the name-uniqueness check.\n- If the exact same name (case-sensitive) already stored is resubmitted, the request is a true no-op — no uniqueness check runs and nothing is written, including no timestamp advance. Renaming to a case-only variant of the current name (e.g. `\"Hooli Corporate\"` → `\"HOOLI CORPORATE\"`) *is* treated as a real change and does get written.\n\n**Optimistic Concurrency:**\n- `expectedLastUpdatedEpoch` is optional. If supplied and it doesn't match the group's current `lastUpdatedEpoch`, the write is rejected with `409` and `code: STALE_UPDATE` — checked before the name-uniqueness check, so a request that is both stale *and* a name collision surfaces `STALE_UPDATE`.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } }, { "name": "id", "in": "path", "description": "The unique ID of the group to rename.", "required": true, "schema": { "type": "string", "example": "group-hooli-corporate" } } ], "requestBody": { "description": "JSON object with the new name. `name` is required.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-security-user-group" }, "examples": { "Rename With Concurrency Check": { "summary": "Rename the group with a concurrency guard", "value": { "name": "Hooli Corporate EMEA", "expectedLastUpdatedEpoch": 1755600000000 } } } } } }, "responses": { "200": { "description": "Updated. The response body is the group in the same shape as `GET /security/user-groups/{id}`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/security-user-group-detail" }, "examples": { "Renamed_Group": { "summary": "Group after rename", "value": { "id": "group-hooli-corporate", "name": "Hooli Corporate EMEA", "type": "security", "userCount": 24, "usedIn": { "securityTemplates": [ { "id": "tmpl-hooli-apac-viewers", "name": "Hooli APAC Viewers" } ] }, "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1734000000000, "createdDate": "2024-12-12T12:00:00.000Z", "lastUpdatedBy": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec", "lastUpdatedEpoch": 1755600500000, "lastUpdatedDate": "2025-08-19T12:08:20.000Z" } } } } } }, "400": { "description": "Bad request — missing/blank/oversized `name`, unexpected field (including `type`), or non-numeric `expectedLastUpdatedEpoch`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Missing_Name": { "value": { "status": "error", "message": "name is required" } }, "Name_Too_Long": { "value": { "status": "error", "message": "name must be 255 characters or fewer" } }, "Unexpected_Type_Field": { "value": { "status": "error", "message": "Unexpected field: type" } } } } } }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no group exists for this id and customer, or it's a `channel`-type group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Security user group not found" } } } }, "409": { "description": "Conflict — either `expectedLastUpdatedEpoch` no longer matches (checked first), or the rename target is already taken by a different group. Distinguish using `code`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "STALE_UPDATE", "DUPLICATE_GROUP_NAME" ] }, "details": { "type": "object", "description": "Present only when `code` is `DUPLICATE_GROUP_NAME`.", "properties": { "existingGroupId": { "type": "string" } } } } }, "examples": { "Stale_Update": { "value": { "status": "error", "message": "Group was modified by another request", "code": "STALE_UPDATE" } }, "Duplicate_Group_Name": { "value": { "status": "error", "message": "A security user group with the same name already exists", "code": "DUPLICATE_GROUP_NAME", "details": { "existingGroupId": "group-hooli-emea" } } } } } } } } }, "delete": { "operationId": "DeleteSecurityUserGroup", "tags": [ "SECURITY GROUPS" ], "summary": "(NEW!) Delete Security User Group", "description": "Permanently delete a security user group the authenticated customer owns. There is no force-delete override — mirrors role delete.\n\n**Delete Rules:**\n- Group must exist for the authenticated customer (or not be a `channel`-type group).\n- Deletion is blocked when either at least one user currently has this group, or at least one security template still references it. Both conditions are checked and reported together.\n- The group is not silently stripped from security templates or from users' memberships to allow the delete — the caller must resolve the blockers first.\n\n**This action is permanent and cannot be undone.**\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "The unique ID of the group to delete.", "required": true, "schema": { "type": "string", "example": "group-hooli-corporate" } } ], "responses": { "204": { "description": "No Content. The security user group has been permanently deleted." }, "401": { "description": "Unauthorized. Missing or unparseable identity on the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — no group exists for the provided ID and customer, or it's a `channel`-type group.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Security user group not found" } } } }, "409": { "description": "Conflict — the group is in use and cannot be deleted.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" }, "code": { "type": "string", "enum": [ "GROUP_IN_USE" ] }, "details": { "type": "object", "properties": { "userCount": { "type": "integer", "description": "Number of users currently in this group." }, "securityTemplates": { "type": "array", "description": "Security templates still referencing this group.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } } } } } } } }, "example": { "status": "error", "message": "Group is in use and cannot be deleted", "code": "GROUP_IN_USE", "details": { "userCount": 24, "securityTemplates": [ { "id": "tmpl-hooli-apac-viewers", "name": "Hooli APAC Viewers" } ] } } } } } } } }, "/user": { "get": { "operationId": "GetCurrentUser", "tags": [ "USERS" ], "summary": "Get Current User Profile", "description": "Use this endpoint to get the user profile information for the account that you've authenticated against the Tenovos API with. \nThis is useful when needing to check which groups you are in which may restrict the API calls you can make.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } }, "post": { "operationId": "CreateUser", "tags": [ "USERS" ], "summary": "Create User", "description": "Use this endpoint to create a new user account in the system. You must have User Management role privilege and Security Template Management role privilege in order to create a user and assign groups.\nThis endpoint can be used to create local or federated users.\n\n**Average Response Time:** 5140ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserCreateRequest" } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/user/{id}": { "get": { "operationId": "GetUser", "tags": [ "USERS" ], "summary": "Get User Profile by ID", "description": "Current user will get its profile information in response.\nUser will also get ID of a role assigned to them and a list of group IDs they belong to.\n\n**Average Response Time:** 154ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "A User Profile ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "format": "uuid", "x-nullable": false, "maxLength": 36, "minLength": 36, "example": "4e428628-2537-40b5-91a4-5393cbf167df" } } ], "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_User_ID": { "value": { "message": "User not found" } } } } } } } }, "patch": { "operationId": "UpdateUser", "tags": [ "USERS" ], "summary": "Update User Attributes", "description": "Update User Profile attributes such as First Name, Last Name, Friendly Name, Email, Company, Country, Contact, Phone, and User Role. The user role can be updated by sending either role id or role name.\n\n**Average Response Time:** 1587ms", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a User Profile ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateRequest" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/User" } } } }, "400": { "description": "Bad Request, one or more of the required fields are not provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "Missing_Required_Fields": { "value": { "status": "error", "message": "Bad Request: one or more of the required fields are not provided" } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_User_ID": { "value": { "message": "User not found" } } } } } } } } }, "/user/{id}/add-to-group": { "patch": { "operationId": "AddUserToGroup", "tags": [ "USERS" ], "summary": "Add User to Group", "description": "Assign a Security Group to a User Profile.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a User Profile ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateSecurityGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateSecurityGroupResponse" } } } }, "400": { "description": "Bad Request, Group is not valid or User is already part of group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "GroupAlreadyAssigned": { "value": { "status": "error", "message": "Bad Request: User is already part of this group." } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_User_ID": { "value": { "message": "User not found" } } } } } } } } }, "/user/{id}/remove-from-group": { "patch": { "operationId": "DeleteGroupFromUser", "tags": [ "USERS" ], "summary": "Remove User from Group", "description": "Remove an assigned Security Group from a User Profile.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "id", "in": "path", "description": "Specify a User Profile ID.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateSecurityGroupRequest" } } }, "required": true }, "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserUpdateSecurityGroupResponse" } } } }, "400": { "description": "Bad Request, Group is not valid or User is not part of group", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorResponse" }, "examples": { "UserNotInGroup": { "value": { "status": "error", "message": "Bad Request: User is not part of this group." } } } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } }, "Incorrect_User_ID": { "value": { "message": "User not found" } } } } } } } } }, "/user/search/{searchText}": { "get": { "operationId": "GetUserByText", "deprecated": true, "tags": [ "USERS" ], "summary": "Search User Profiles", "description": "Use this endpoint to retrieve a list of User Profiles matching the search keyword provided in the request parameter. Do not enter your search term wrapped in quotation marks.\nProvided keyword will be matched against the user attributes case insensitively - First Name, Last Name, Friendly Name, Username, Email, Phone, Company, Contact, Country, Status, Group Names, and Role Name. Entering \"*\" as your search term will return all users.\nThe response is formatted as an area of objects, with each user account being returned as an object, as well as a key called 'count', which indicates how many accounts met the search critera. A maximum limit of 100 accounts will be returned in the response. \nIn the case that more than 100 accounts meet the search criteria, pagination using the optional 'from' and 'limit' query parameters will be required to retrieve all accounts.\n\n**The user performing this action must have the 'User Management' role privilege.**\n\n**How to use pagination:**\nPagination should be used when the amount of user accounts that match the entered search term exceeds the amount of users (100) returned in a single response. Paginating through the results will require making more than one call to this endpoint.\nTo retrieve the first 100 users, in your query parameters, set your 'from' value to 0, and your 'limit' value to 100. To return the next set of 100 users, leave your 'limit' value as 100, but set your 'from' value to 100. \n\nContinue to repeat this process of adding 100 to your 'from' value until all user account results are captured.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "searchText", "in": "path", "description": "Specify searchText to search across user attributes.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Specify the starting position for the next result set.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Specify the maximum number of records to return each call.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body will be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSearchResponse" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "examples": { "Missing_X-API-key": { "value": { "message": "Forbidden" } } } } } } } } }, "/user/searches": { "get": { "operationId": "getSavedSearches", "tags": [ "SEARCH" ], "summary": "Get Saved Searches", "description": "Use this endpoint to retrieve all Saved Searches available to the signed in user.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSavedSearches" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/users": { "get": { "operationId": "ListUsers", "tags": [ "USERS" ], "summary": "(NEW!) List Users (Paginated)", "description": "Retrieve an offset-paginated, searchable list of users for the authenticated customer. Supports free-text search, status/role/group filtering, and server-side sorting.\n\nThis endpoint supersedes `GET /user/search/{searchText}` — it adds `userName` to the searchable fields and returns `createdEpoch`/`lastUpdatedEpoch` on every result.\n\n**Defaults:**\n- `from` defaults to `0`.\n- `limit` defaults to `100` (values above `100` are capped to `100`).\n- `sortField` defaults to `firstName`.\n- `order` defaults to `desc`.\n\n**Business Rules:**\n- `searchTerm` is trimmed and, when non-empty, matched as a case-insensitive substring against first name, last name, friendly name, email, status, phone, company, country, contact, `userName`, role name, and group name. Literal `%` and `_` are treated as text, not SQL wildcards. Omitted returns all users — no `*` sentinel required.\n- `role` and `group` are comma-separated lists of role/group **names** (not ids); multiple values use OR logic.\n- `status` accepts `enabled`, `disabled`, `pendingApproval`. `allDisabled` is not a supported value and is rejected with `400`. Omitted returns users of any status.\n- `groupCount` (as a `sortField` value) sorts by the number of group ids in the user's `groups` array; a user with no groups sorts as `0`, never `null`. It does not add a `groupCount` field to the response.\n- `roleName` (as a `sortField` value) sorts using the user's associated role name.\n- `status` (as a `sortField` value) sorts alphabetically by the stored status value.\n- Each result includes both the id and display name for its role (`roleId`/`roleName`) and for each group (`groupId`/`groupName`) — the front end does not need to resolve ids to names itself.\n- `connectUser` indicates whether the user can access Tenovos Connect. `connectRole` holds that user's Tenovos Connect role and is `null` when `connectUser` is `false`. The `connectUser` query parameter filters on this same field: `true` returns only Tenovos Connect users, `false` returns only users who are not, and omitting it applies no filter at all rather than defaulting to either.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "searchTerm", "in": "query", "description": "Case-insensitive substring match against first name, last name, friendly name, email, status, phone, company, country, contact, userName, role name, and group name. Literal `%` and `_` are treated as text. Omitted returns all users.", "required": false, "schema": { "type": "string", "example": "smith" } }, { "name": "role", "in": "query", "description": "Comma-separated list of role names. Multiple values use OR logic.", "required": false, "schema": { "type": "string", "example": "Admin,Content Editor" } }, { "name": "group", "in": "query", "description": "Comma-separated list of group names. A user matches when they belong to at least one supplied group.", "required": false, "schema": { "type": "string", "example": "Marketing" } }, { "name": "status", "in": "query", "description": "Filters by account status. Omitted returns users of any status. `allDisabled` is not supported.", "required": false, "schema": { "type": "string", "enum": [ "enabled", "disabled", "pendingApproval" ] } }, { "name": "connectUser", "in": "query", "description": "Filters by Tenovos Connect access, matching the `connectUser` field on each result. `true` returns only Tenovos Connect users; `false` returns only users who are not. Omitted applies no filter and returns both.", "required": false, "schema": { "type": "boolean", "example": true } }, { "name": "from", "in": "query", "description": "Result offset from which to start. Defaults to `0`.", "required": false, "schema": { "type": "integer", "default": 0, "example": 0 } }, { "name": "limit", "in": "query", "description": "Number of results to return per page. Defaults to `100`, maximum `100` (values above `100` are capped).", "required": false, "schema": { "type": "integer", "default": 100, "example": 100 } }, { "name": "sortField", "in": "query", "description": "Field to sort results by. Defaults to `firstName`.", "required": false, "schema": { "type": "string", "enum": [ "firstName", "lastName", "emailId", "userName", "friendlyName", "status", "phone", "contact", "country", "company", "createdEpoch", "lastUpdatedEpoch", "groupCount", "roleName" ], "default": "firstName" } }, { "name": "order", "in": "query", "description": "Sort direction. Defaults to `desc`.", "required": false, "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } } ], "responses": { "200": { "description": "Offset-paginated list of users matching the search and filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/user-list" }, "examples": { "Users_Page": { "summary": "A page of users", "value": { "users": [ { "userId": "7d675ef0-f423-11e9-8071-89c0c4052141", "customerId": "1234567890", "emailId": "erlich.bachman@piedpiper.com", "firstName": "Erlich", "lastName": "Bachman", "roleId": "7d5620e0-f423-11e9-8071-89c0c4052141", "roleName": "Admin", "status": "enabled", "groups": [ { "groupId": "7d6207c0-f423-11e9-8071-89c0c4052141", "groupName": "Marketing" } ], "connectUser": true, "connectRole": "Admin", "userName": "erlich.bachman", "phone": "15551234565", "contact": "Richard Hendricks", "country": "USA", "company": "Pied Piper", "friendlyName": "Erlich Bachman", "createdEpoch": 1690000000000, "lastUpdatedEpoch": 1700000000000 } ], "pageInfo": { "from": 0, "limit": 100, "total": 842, "hasNextPage": true } } } } } } }, "400": { "description": "Bad request — invalid `status`, `connectUser`, `sortField`, `order`, or `from`.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Invalid_Status": { "value": { "status": "error", "message": "Invalid status. Allowed values: enabled, disabled, pendingApproval" } }, "Invalid_Connect_User": { "value": { "status": "error", "message": "Invalid connectUser. Allowed values: true, false" } }, "Invalid_Sort_Field": { "value": { "status": "error", "message": "Invalid sortField. Allowed values: firstName, lastName, emailId, userName, friendlyName, status, phone, contact, country, company, createdEpoch, lastUpdatedEpoch, groupCount, roleName" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "An unexpected error occurred" } } } } } } }, "/users/status-counts": { "get": { "operationId": "GetUserStatusCounts", "tags": [ "USERS" ], "summary": "(NEW!) Get User Status Counts", "description": "Retrieve user totals by status for the authenticated customer, calculated in a single grouped query. Backs the User Management screen's status tabs without running a separate paginated `GET /users` query per status.\n\n**Business Rules:**\n- This endpoint does not currently accept any query parameters — the counts always represent the complete user population for the authenticated customer and are unaffected by the search/filter state of `GET /users`. Filtering may be added later as an additive change.\n- All four properties are always returned, including `0` for a status with no matching users.\n- Pending-approval identification preserves the existing User Management status/update-attribution rules.\n\nThe user submitting the request must have the **User Management** privilege.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "User totals by status for the authenticated customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "enabled": { "type": "integer", "description": "Number of enabled users for the authenticated customer.", "example": 842 }, "disabled": { "type": "integer", "description": "Number of disabled users for the authenticated customer.", "example": 130 }, "pendingApproval": { "type": "integer", "description": "Number of users considered pending approval by the existing User Management status rules.", "example": 12 }, "total": { "type": "integer", "description": "Total number of users for the authenticated customer.", "example": 984 } } }, "examples": { "Status_Counts": { "summary": "User totals by status", "value": { "enabled": 842, "disabled": 130, "pendingApproval": 12, "total": 984 } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks the User Management privilege.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "An unexpected error occurred" } } } } } } }, "/template": { "post": { "operationId": "getTemplates", "tags": [ "ADAPTIVE TEMPLATES" ], "summary": "Get Templates", "description": "For customers with the Adaptive Template templates feature, use this endpoint to return a list of all available templates in the system.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdaptiveTemplateSearch" } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/adaptive-templates" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/template/launch": { "post": { "operationId": "launchTemplate", "tags": [ "ADAPTIVE TEMPLATES" ], "summary": "Get Template URL", "description": "Returns a secure URL to open the template in a web browser using template identifier.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation", "required": true, "style": "simple", "explode": false, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "style": "simple", "explode": false, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "The Request Body must be a JSON object", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/launch-template" } } }, "required": true }, "responses": { "200": { "description": "The Response Body is a JSON object.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/launch" } } } }, "401": { "description": "Unauthorized. Missing Authorization or AccessToken or Access Token expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Unauthorized" } } } }, "403": { "description": "Forbidden. Missing X-API-key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GeneralErrorMessageResponse" }, "example": { "message": "Forbidden" } } } } } } }, "/webhooks/endpoint": { "post": { "operationId": "createSubscription", "tags": [ "WEBHOOKS" ], "summary": "Create Endpoint", "description": "Create a subscription based on the topic and event type in order to be notified at your target URL when events about that topic occur.", "parameters": [ { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "responses": { "200": { "description": "Successful Request. Webhook Subscriptions Created Successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhooks" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/webhooks/endpoint/list": { "get": { "operationId": "getEndpointSubscriptionsList", "tags": [ "WEBHOOKS" ], "summary": "List Endpoints", "description": "This endpoint returns an array (List) of all endpoints (your endpoints) and the event types subscribed.", "parameters": [ { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "responses": { "200": { "description": "Successful Request. Endpoints Retrieved Successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/endpoint" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/webhooks/event-type/list": { "get": { "operationId": "getEventTypeList", "tags": [ "WEBHOOKS" ], "summary": "List Event Types", "description": "This endpoint returns an array (List) of all event types.", "parameters": [ { "$ref": "#/components/parameters/before" }, { "$ref": "#/components/parameters/after" }, { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "responses": { "200": { "description": "Successful Request. Event Types Retrieved Successfully.", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/eventType" } } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/webhooks/endpoint/{id}": { "get": { "operationId": "getEndpointById", "tags": [ "WEBHOOKS" ], "summary": "Endpoint by ID", "description": "This endpoint returns a single endpoint and its configuration by ID.", "parameters": [ { "$ref": "#/components/parameters/subscriptionId" }, { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "responses": { "200": { "description": "Successful Request. Endpoint Retrieved Successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/endpoint" } } } }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } }, "patch": { "operationId": "updateEndpointById", "tags": [ "WEBHOOKS" ], "summary": "Update Endpoint", "description": "This endpoint updates a single endpoint and its configuration by ID.", "parameters": [ { "$ref": "#/components/parameters/subscriptionId" }, { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook" } } } }, "responses": { "204": { "description": "Successful Request. Endpoint Updated Successfully." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } }, "delete": { "operationId": "deleteWebhook", "tags": [ "WEBHOOKS" ], "summary": "Delete Endpoint", "description": "Delete a subscription you have to a Webhook based on the ID of the Webhook Subscription", "parameters": [ { "$ref": "#/components/parameters/subscriptionId" }, { "$ref": "#/components/parameters/content-type" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "responses": { "204": { "description": "Successful Request. Webhook Subscription Deleted Successfully." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/webhooks/endpoint/oauth/{endpointId}": { "put": { "operationId": "CreateOauth", "tags": [ "WEBHOOKS" ], "summary": "Add OAuth", "description": "Add an authorized OAuth client to an existing endpoint.", "parameters": [ { "$ref": "#/components/parameters/endpointId" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/webhook-oauthCreate" } } } }, "responses": { "204": { "description": "Successful Request. OAuth Added Successfully." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } }, "delete": { "operationId": "DeleteOauth", "tags": [ "WEBHOOKS" ], "summary": "Remove OAuth", "description": "Remove an authorized OAuth client from an existing endpoint.", "parameters": [ { "$ref": "#/components/parameters/endpointId" }, { "$ref": "#/components/parameters/authorization" }, { "$ref": "#/components/parameters/api-key" } ], "responses": { "204": { "description": "Successful Request. Webhook Subscription Deleted Successfully." }, "400": { "$ref": "#/components/responses/400" }, "401": { "$ref": "#/components/responses/401" }, "403": { "$ref": "#/components/responses/403" }, "503": { "$ref": "#/components/responses/503" } } } }, "/rights/associations/removal": { "post": { "operationId": "RemoveRightsAssociation", "tags": [ "RIGHTS MANAGEMENT" ], "summary": "(NEW!) Remove Rights Association", "description": "Remove a rights-management association between two objects, along with any downstream relationships that are only justified by that association. This replaces the client-side relationship traversal previously performed by the Rights Management UI — the caller supplies the two objects participating in the association, and the backend determines and removes the applicable relationship set.\n\n**Supported Associations:**\n- `Project <-> Agreement` — removes the direct relationship and any downstream relationships justified solely by it. The Project and Agreement objects are not deleted. Relationships still justified by another valid association are preserved. Works regardless of which object is `primary`.\n- `Agreement <-> Entity` — removes the direct relationship and any downstream relationships justified solely by it. The Agreement and Entity objects are not deleted. Relationships still justified by another valid association are preserved. Works regardless of which object is `primary`.\n- `Agreement -> Right` — a Right is contained by its Agreement, so removing this association soft-deletes the Right using the existing Right deletion behavior.\n\nAny other object-type pair is unsupported and returns `400`. Relationship types such as `child`, `derivative`, and `placed-graphic` are out of scope for this endpoint.\n\n**Business Rules:**\n- `customerId` and the requesting user's identity are read exclusively from the authenticated ID token — they are never accepted from the request body.\n- All relationship reads and deletes are scoped to the authenticated customer. Cross-customer objects or relationships are never returned, traversed, or modified.\n- This operation is idempotent — retrying a removal after the applicable relationships have already been removed succeeds without corrupting data or failing solely because those relationships are already absent.\n\nThe user submitting the request must have WRITE authorization for Rights Management.", "parameters": [ { "name": "X-API-Key", "in": "header", "description": "Customer-specific API key required to invoke API.", "required": true, "schema": { "type": "string" } }, { "name": "Authorization", "in": "header", "description": "Provided by Authentication Token creation operation.", "required": true, "schema": { "type": "string" } }, { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "application/json" ] } } ], "requestBody": { "description": "JSON object identifying the two objects participating in the association to remove. Required: `primary`, `secondary`, each with `objectId` and `objectType`.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/remove-rights-association" }, "examples": { "Remove Project Agreement Association": { "summary": "Remove the association between a Project and an Agreement", "value": { "primary": { "objectId": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c", "objectType": "RM - Agreement" }, "secondary": { "objectId": "42ac8e81-8113-49fd-977b-a2001ad3d7c8", "objectType": "RM - Project" } } }, "Remove Agreement Right Association": { "summary": "Remove an Agreement's containment of a Right (soft-deletes the Right)", "value": { "primary": { "objectId": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c", "objectType": "RM - Agreement" }, "secondary": { "objectId": "9b1f3c2a-1234-4a54-94a8-e6c7733fe92c", "objectType": "RM - Right" } } } } } } }, "responses": { "200": { "description": "Association removal completed successfully. `removed.objects` is empty for `Project <-> Agreement` and `Agreement <-> Entity` removals; for `Agreement -> Right` removals it contains the soft-deleted Right.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/rights-association-removal" }, "examples": { "Project Agreement Removed": { "summary": "A single Project <-> Agreement relationship removed", "value": { "status": "success", "removed": { "relationships": [ { "primaryId": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c", "secondaryId": "42ac8e81-8113-49fd-977b-a2001ad3d7c8", "linkType": "rm-project-agreement" } ], "objects": [] } } }, "Agreement Right Removed": { "summary": "An Agreement -> Right containment removed, soft-deleting the Right", "value": { "status": "success", "removed": { "relationships": [ { "primaryId": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c", "secondaryId": "9b1f3c2a-1234-4a54-94a8-e6c7733fe92c", "linkType": "rm-agreement-right" } ], "objects": [ { "id": "9b1f3c2a-1234-4a54-94a8-e6c7733fe92c", "objectType": "RM - Right", "status": "deleted", "lastUpdatedEpoch": 1773070355217, "lastUpdatedDate": "2026-03-09T15:32:35.217Z" } ] } } } } } } }, "400": { "description": "Bad request — missing required fields or an unsupported `objectType` pair.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "examples": { "Missing_Field": { "value": { "status": "error", "message": "primary.objectId is required" } }, "Unsupported_Association": { "value": { "status": "error", "message": "Unsupported association between objectType RM - Asset and RM - Project" } } } } } }, "401": { "description": "Unauthorized. Missing or invalid token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "Unauthorized" } } } }, "403": { "description": "Forbidden — user lacks WRITE authorization for Rights Management.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "User does not have the privilege to perform action" } } } }, "404": { "description": "Not found — the supplied object or association cannot be resolved for the authenticated customer.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No association found for the provided objects" } } } }, "422": { "description": "Unprocessable Entity — no privilege mapping found for the token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string" } } }, "example": { "status": "error", "message": "No privilege mapping found for this token" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "BasicAuth": { "type": "http", "scheme": "basic" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-Key" } }, "schemas": { "Action": { "type": "object", "properties": { "createdBy": { "type": "string", "description": "User ID who initiated this Action", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c405214e" }, "createdEpoch": { "type": "integer", "description": "Creation time in milliseconds", "example": 1608745510614 }, "currentVersion": { "type": "string", "description": "Current version flag", "example": "Y", "enum": [ "Y", "N" ] }, "customerId": { "type": "string", "description": "Customer ID of Created By User's Account", "example": "123203455" }, "fileId": { "type": "string", "description": "Asset File ID", "format": "uuid" }, "filename": { "type": "string", "description": "Action file name", "example": "action.png" }, "fileState": { "type": "string", "description": "Action content file state", "enum": [ "available", "recycle bin" ] }, "lastUpdatedBy": { "type": "string", "description": "User ID who last updated the asset", "format": "uuid", "example": "dfeb57c1-b149-4b15-920f-3f40ff3423ad" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last update time in milliseconds", "example": 1612333543954 }, "metadata": { "$ref": "#/components/schemas/MetadataDocument" }, "metadataDenormalized": { "type": "object", "description": "Metadata document is a flat list of metadata attributes and values, where values are either in text values or foreign keys / referential values" }, "metadataState": { "type": "string", "description": "Action metadata state", "example": "available", "enum": [ "available", "recycle bin" ] }, "metadataTemplateId": { "type": "string", "description": "Metadata Template ID", "format": "uuid", "example": "ea6eb24d-adef-4380-bd02-f64f567c437f" }, "objectId": { "type": "string", "description": "Action Object ID", "format": "uuid", "example": "e6f4bd5e-9bea-43cb-b15e-22582fa5322e" }, "objectType": { "type": "string", "description": "Action Object type", "example": "Action", "enum": [ "Action" ] }, "originalFileId": { "type": "string", "description": "The ID of the original version of the Action", "format": "uuid", "example": "003391e4-e78a-4186-b2d7-b5d4fcbe445d" }, "renditions": { "$ref": "#/components/schemas/AssetRenditions" }, "securityTemplateIds": { "type": "array", "description": "List of Security Template IDs", "items": { "type": "string", "format": "uuid", "example": "7d6f4e30-f423-11e9-8071-89c0c4052156" } }, "securityDenormalized": { "$ref": "#/components/schemas/AssetSecurityDenormalized" }, "technicalMetadata": { "$ref": "#/components/schemas/AssetTechnicalMetadata" }, "versionNumber": { "type": "integer", "description": "Action version number", "deprecated": true } } }, "Asset": { "type": "object", "properties": { "createdBy": { "type": "string", "description": "User ID who created this Asset", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c405214e" }, "createdEpoch": { "type": "integer", "description": "Creation time in milliseconds", "example": 1608745510614 }, "currentVersion": { "type": "string", "description": "Current version flag", "example": "Y", "enum": [ "Y", "N" ] }, "customerId": { "type": "string", "description": "Customer ID of Created By User's Account", "example": "123203455" }, "fileId": { "type": "string", "description": "Asset File ID", "format": "uuid" }, "filename": { "type": "string", "description": "Asset content file name", "example": "adventure-alps-beautiful-landscape-2444403.jpg" }, "fileState": { "type": "string", "description": "Asset content file state", "enum": [ "available", "recycle bin" ] }, "lastUpdatedBy": { "type": "string", "description": "User ID who last updated the asset", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c40133ds" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last update time in milliseconds", "example": 1612333543954 }, "metadata": { "$ref": "#/components/schemas/MetadataDocument" }, "metadataDenormalized": { "type": "object", "description": "Metadata document is a flat list of metadata attributes and values, where values are either in text values or foreign keys / referential values" }, "metadataState": { "type": "string", "description": "Asset metadata state", "example": "available", "enum": [ "available", "recycle bin" ] }, "metadataTemplateId": { "type": "string", "description": "Metadata Template ID", "format": "uuid", "example": "ea6eb24d-adef-4380-bd02-f64f567c437f" }, "objectId": { "type": "string", "description": "Asset Object ID", "format": "uuid", "example": "e6f4bd5e-9bea-43cb-b15e-22582fa5322e" }, "objectType": { "type": "string", "description": "Asset Object type", "example": "Asset", "enum": [ "Asset" ] }, "originalFileId": { "type": "string", "description": "The ID of the original version of the file", "format": "uuid", "example": "003391e4-e78a-4186-b2d7-b5d4fcbe445d" }, "renditions": { "$ref": "#/components/schemas/renditions" }, "securityTemplateIds": { "type": "array", "description": "List of Security Template IDs", "items": { "type": "string", "format": "uuid", "example": "7d6f4e30-f423-11e9-8071-89c0c4052156" } }, "securityDenormalized": { "$ref": "#/components/schemas/AssetSecurityDenormalized" }, "technicalMetadata": { "$ref": "#/components/schemas/AssetTechnicalMetadata" }, "versionNumber": { "type": "integer", "description": "Asset version number", "deprecated": true }, "presignedURL": { "type": "string", "description": "The URL to download the file. Populated for download requests." }, "linkType": { "type": "string" }, "relationshipId": { "type": "string", "format": "uuid" }, "secondaryId": { "type": "string" } } }, "AssetBulkEditRequest": { "required": [ "metadataTemplateId", "objectIds" ], "type": "object", "properties": { "metadataTemplateId": { "type": "string", "description": "Metadata Template ID to assign to the edited Assets.", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "ea6eb24d-adef-4080-bd02-f64f567c437f" }, "metadataDocument": { "type": "array", "description": "An array of metadata attribute operations", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetBulkEditStringValue" }, { "$ref": "#/components/schemas/AssetBulkEditDateValue" }, { "$ref": "#/components/schemas/AssetBulkEditRestrictedVocabularyValue" }, { "$ref": "#/components/schemas/AssetBulkEditMultiValue" }, { "$ref": "#/components/schemas/AssetBulkEditGridValue" } ] } }, "objectIds": { "type": "array", "description": "An array of Asset Object IDs", "items": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "e55bdb0c-022b-475d-9e26-9d74552e1e81" } }, "securityTemplateIds": { "type": "array", "description": "An array of Security Template IDs.", "items": { "type": "string", "format": "uuid", "example": "a7099f22-4585-4533-88b4-a5e9dff928bc" } }, "securityTemplateOp": { "type": "string", "description": "Operation to either replace or append to the currently assigned list of Security Template IDs with the provided list of Security Template IDs.", "enum": [ "replace", "append" ] } } }, "AssetBulkEditStringValue": { "required": [ "metadataDefinitionId", "metadataDefinitionValue", "operation" ], "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Attribute ID retrieved from metadata template.", "format": "uuid", "example": "dfeb57c1-b149-4b15-920f-3f40ff0b959a" }, "metadataDefinitionValue": { "type": "string", "description": "Metadata value", "example": "Photo" }, "operation": { "type": "string", "example": "replace", "enum": [ "replace", "append" ] } } }, "AssetBulkEditDateValue": { "required": [ "metadataDefinitionId", "metadataDefinitionValue", "operation" ], "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionValue": { "type": "string", "description": "Date formatted as **mm/dd/yyyy** string", "example": "02/10/2021" }, "operation": { "type": "string", "example": "replace", "enum": [ "replace" ] } } }, "AssetBulkEditGridValue": { "required": [ "metadataDefinitionId", "metadataDefinitionValue", "operation" ], "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionTableValue": { "type": "array", "description": "Array representing the rows in the grid.", "items": { "$ref": "#/components/schemas/AssetBulkEditTableRow" } }, "operation": { "type": "string", "example": "append", "enum": [ "replace", "append" ] } } }, "AssetBulkEditMultiValue": { "required": [ "metadataDefinitionId", "metadataDefinitionValue", "operation" ], "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionValue": { "type": "array", "description": "An array of values.", "items": { "$ref": "#/components/schemas/AssetBulkEditMultiValue_metadataDefinitionValue" } }, "operation": { "type": "string", "example": "append", "enum": [ "replace", "append" ] } } }, "AssetBulkEditResponse": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Job ID of the submitted Bulk Edit Job.", "format": "uuid", "example": "5fa57655-c56c-47d3-a409-751fd5fd9735" }, "collectionId": { "type": "string", "description": "Collection ID of the Collection containing the Assets being bulk edited.", "format": "uuid", "example": "7c6a6a3b-cac0-4218-be3b-515e0f9cb967" } } }, "AssetBulkEditRestrictedVocabularyValue": { "required": [ "metadataDefinitionId", "metadataDefinitionValue", "operation" ], "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid" }, "metadataDefinitionValue": { "$ref": "#/components/schemas/AssetBulkEditRestrictedVocabularyValue_metadataDefinitionValue" }, "operation": { "type": "string", "example": "replace", "enum": [ "replace" ] } } }, "AssetBulkEditTableRow": { "type": "array", "description": "Array defining the columns of the grid.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetBulkEditStringValue" }, { "$ref": "#/components/schemas/AssetBulkEditRestrictedVocabularyValue" }, { "$ref": "#/components/schemas/AssetBulkEditDateValue" } ] } }, "AssetCreateRequest": { "required": [ "filename", "metadata", "metadataTemplateId", "securityTemplateIds" ], "type": "object", "properties": { "originalFileId": { "type": "string", "description": "ID of the file. When provided a new version will be created.", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "ea6eb24d-adef-4080-bd02-f64f567c437f" }, "metadataTemplateId": { "type": "string", "description": "ID of metadata template to apply.", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "ea6eb24d-adef-4080-bd02-f64f567c437f" }, "metadata": { "$ref": "#/components/schemas/MetadataDocument" }, "securityTemplateIds": { "type": "array", "description": "Array of Security Template IDs", "items": { "type": "string", "format": "uuid", "example": "7d6f4e30-f423-11e9-8071-89c0c4052141" } }, "filename": { "type": "string", "description": "Asset file name." }, "contentPath": { "type": "string", "description": "S3 path to the file. Required only for Federated files." }, "skipTranscode": { "type": "boolean", "description": "Flag to skip content transformation. Required only for Federated files." }, "filesize": { "type": "number", "description": "Size of file in bytes" } }, "description": "JSON Object included when submitting a request to create an asset. The **Metadata** property is required and nullable." }, "AssetContent": { "type": "object", "properties": { "presignedURL": { "type": "string", "description": "RL to download an Asset content", "format": "url", "example": "https://contentstore.example.com/masters/055f4b24-0218-45ce-8d8f-2d39be0b676d/aerial-shot-1612461.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAYKPOCFJYXPN3EMXM%2F20210222%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210222T222207Z&X-Amz-Expires=20&X-Amz-Signature=444a0d4fd145a6c33a51494c914a878f44555c289f5ac70ee354e98bd1dd0ac&X-Amz-SignedHeaders=host" } } }, "AssetExposeRefRendition": { "type": "object", "properties": { "componentType": { "type": "string", "example": "rendition" }, "componentRef": { "type": "array", "items": { "type": "string", "example": "imageThumb" } }, "expiration": { "type": "integer", "example": 3000 } } }, "AssetExposeRefObject": { "type": "object", "properties": { "componentType": { "type": "string", "example": "object" }, "componentRef": { "type": "string", "example": "original" }, "expiration": { "type": "integer", "description": "Expiration Time in seconds.", "example": 3000 } } }, "AssetExposeRequest": { "type": "array", "items": { "$ref": "#/components/schemas/AssetExposeRequest_inner" } }, "AssetExposeResponse": { "type": "array", "items": { "$ref": "#/components/schemas/AssetExposeResponse_inner" } }, "AssetExposeRenditionResponse": { "type": "object", "properties": { "renditionType": { "type": "string", "example": "imageThumb" }, "componentRef": { "type": "string", "example": "imageThumb" }, "expires": { "type": "integer", "example": 3000 }, "url": { "type": "string", "example": "https://contentstore.s3.amazonaws.com/1566292944864/67f23946-24d9-455d-9029-fe3012904564/4c3e98f2-03d9-41b4-8970-63a1528bb33d-200x200.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2HGSK63JE6U37KZD%2F20210222%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210222T221841Z&X-Amz-Expires=300&X-Amz-Signature=a078326023b77caff6e3c589d5572506edcc999a81e97c09766d096493e9c515&X-Amz-SignedHeaders=host" } } }, "AssetExposeObjectResponse": { "type": "object", "properties": { "renditionType": { "type": "string", "example": "original" }, "componentRef": { "type": "string", "example": "original" }, "expires": { "type": "integer", "example": 3000 }, "url": { "type": "string", "example": "https://contentstore.s3.amazonaws.com/masters/67f23946-24d9-455d-9029-fe3012903454/Example%20Document%20PowerPoint%20Presentation.ppt?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIA2HGSK63JE6U37KZD%2F20210222%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210222T221842Z&X-Amz-Expires=300&X-Amz-Signature=abf7fffbd63215614a0f566ff1f31d36d102d5726e56ab916812bf5678f756b0&X-Amz-SignedHeaders=host" } } }, "AssetDeleteRequest": { "type": "object", "properties": { "action": { "type": "string", "description": "specifies whether to delete or un-delete the asset", "example": "delete", "enum": [ "delete", "undelete" ] }, "deleteType": { "type": "string", "description": "Delete Type: full, content, or metadata", "example": "full", "enum": [ "full" ] } }, "description": "JSON request message to soft delete or un-delete an Asset. Currently only full delete type is supported." }, "AssetImageMetadata": { "type": "object", "properties": { "fileName": { "type": "string", "example": "adventure-alps-beautiful-landscape-2444403.jpg" }, "fileSize": { "type": "string", "example": "4.4 MB" }, "fileType": { "type": "string", "example": "JPEG" }, "fileTypeExtension": { "type": "string", "example": "jpg" }, "mimeType": { "type": "string", "example": "image/jpeg" }, "jfifVersion": { "type": "string", "example": "1.01" }, "resolutionUnit": { "type": "string", "example": "inches" }, "xResolution": { "type": "string", "example": "72" }, "yResolution": { "type": "string", "example": "72" }, "profileCMMType": { "type": "string", "example": "Linotronic" }, "profileVersion": { "type": "string", "example": "2.1.0" }, "profileClass": { "type": "string", "example": "Display Device Profile" }, "colorSpaceData": { "type": "string", "example": "RGB" }, "profileConnectionSpace": { "type": "string", "example": "XYZ" }, "profileDateTime": { "type": "string", "example": "1998:02:09 06:49:00" }, "profileFileSignature": { "type": "string", "example": "acsp" }, "primaryPlatform": { "type": "string", "example": "Microsoft Corporation" }, "cmmFlags": { "type": "string", "example": "Not Embedded, Independent" }, "deviceManufacturer": { "type": "string", "example": "Hewlett-Packard" }, "deviceModel": { "type": "string", "example": "sRGB" }, "deviceAttributes": { "type": "string", "example": "Reflective, Glossy, Positive, Color" }, "renderingIntent": { "type": "string", "example": "Perceptual" }, "connectionSpaceIlluminant": { "type": "string", "example": "0.9642 1 0.82491" }, "profileCreator": { "type": "string", "example": "Hewlett-Packard" }, "profileID": { "type": "string", "example": "0" }, "profileCopyright": { "type": "string", "example": "Copyright (c) 1998 Hewlett-Packard Company" }, "profileDescription": { "type": "string", "example": "sRGB IEC61966-2.1" }, "mediaWhitePoint": { "type": "string", "example": "0.95045 1 1.08905" }, "mediaBlackPoint": { "type": "string", "example": "0 0 0" }, "redMatrixColumn": { "type": "string", "example": "0.43607 0.22249 0.01392" }, "greenMatrixColumn": { "type": "string", "example": "0.38515 0.71687 0.09708" }, "blueMatrixColumn": { "type": "string", "example": "0.14307 0.06061 0.7141" }, "deviceMfgDesc": { "type": "string", "example": "IEC http://www.iec.ch" }, "deviceModelDesc": { "type": "string", "example": "IEC 61966-2.1 Default RGB color space - sRGB" }, "viewingCondDesc": { "type": "string", "example": "Reference Viewing Condition in IEC61966-2.1" }, "viewingCondIlluminant": { "type": "string", "example": "19.6445 20.3718 16.8089" }, "viewingCondSurround": { "type": "string", "example": "3.92889 4.07439 3.36179" }, "viewingCondIlluminantType": { "type": "string", "example": "D50" }, "luminance": { "type": "string", "example": "76.03647 80 87.12462" }, "measurementObserver": { "type": "string", "example": "CIE 1931" }, "measurementBacking": { "type": "string", "example": "0 0 0" }, "measurementGeometry": { "type": "string", "example": "Unknown" }, "measurementFlare": { "type": "string", "example": "0.999%" }, "measurementIlluminant": { "type": "string", "example": "D65" }, "technology": { "type": "string", "example": "Cathode Ray Tube Display" }, "redToneReproductionCurve": { "type": "string", "example": "(Binary data 2060 bytes, use -b option to extract)" }, "greenToneReproductionCurve": { "type": "string", "example": "(Binary data 2060 bytes, use -b option to extract)" }, "blueToneReproductionCurve": { "type": "string", "example": "(Binary data 2060 bytes, use -b option to extract)" }, "imageWidth": { "type": "integer", "example": 3264 }, "imageHeight": { "type": "integer", "example": 4080 }, "encodingProcess": { "type": "string", "example": "Baseline DCT, Huffman coding" }, "bitsPerSample": { "type": "number", "example": 8 }, "colorComponents": { "type": "integer", "example": 3 }, "yCbCrSubSampling": { "type": "string", "example": "YCbCr4:2:0 (2 2)" }, "imageSize": { "type": "string", "example": "3264x4080" }, "megapixels": { "type": "number", "example": 13.3 } } }, "AssetLinkDeleteResponse": { "type": "array", "description": "The array returns a status for each secondary ID object. Some could have been successful and some are not", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetLinkUpdateSuccessResponse" }, { "$ref": "#/components/schemas/AssetLinkUpdateFailureResponse" } ] } }, "AssetLinkUpdateSuccessResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Relationship deleted successfully" }, "relationshipId": { "type": "string", "format": "uuid", "example": "f81769d1-8e93-4af7-856e-56ea30ec1038-c91f8b40-a7ba-476c-b52f-341952f6c250" } } }, "AssetLinkUpdateFailureResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "relationship retrieval failed [f81769d1-8e93-4af7-856e-56ea30ec1038-1f426f2f2-69bc-43a8-9e4b-a857af81972b]" } } }, "AssetMultipartUploadRequest": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "filesize": { "type": "integer", "example": 335226108 }, "action": { "type": "string", "description": "Either **complete** or **abort** as the action to finalize the multipart upload. This field is case sensitive.", "example": "complete", "enum": [ "complete", "abort" ] }, "originalFileId": { "type": "string", "format": "uuid" }, "uploadId": { "type": "string", "example": "gR5XHJZpuDv8UizdpSGuwONje0GbMHnCWXS5zTTVkyVINURV6iraWLhpM7Sy7oy65utAgPcm2FfM4fRp4oVga4ggEzD811aS1tke_F0iIIXX1kV7m6UouytsNE0oL8fzo2Zr2JCqwRyhFTXp98zjdQ--" }, "parts": { "type": "array", "items": { "$ref": "#/components/schemas/AssetMultipartUploadRequest_parts" } } } }, "AssetMultipartUploadResponse": { "type": "object", "properties": { "fileId": { "type": "string", "format": "uuid" }, "filename": { "type": "string" }, "action": { "type": "string", "example": "Complete/Abort" }, "uploadId": { "type": "string", "example": "gR5XHJZpuDv8UizdpSGuwONje0GbMHnCWXS5zTTVkyVINURV6iraWLhpM7Sy7oy65utAgPcm2FfM4fRp4oVga4ggEzD811aS1tke_F0iIIXX1kV7m6UouytsNE0oL8fzo2Zr2JCqwRyhFTXp98zjdQ--" }, "s3Key": { "type": "string", "example": "masters/843ec17f-9491-4cfa-b840-faa299973207/2-vid.mp4" }, "status": { "type": "string", "example": "success" } } }, "AssetRelationship": { "type": "object", "properties": { "secondaryId": { "type": "string", "description": "ID of the secondary asset", "format": "uuid" }, "createdEpoch": { "type": "integer", "description": "Created date in epoch format", "example": 1613677209722 }, "customerId": { "type": "string", "example": "15716718541456" }, "linkType": { "type": "string", "description": "The type of link.", "enum": [ "child", "derivative", "placed-graphic" ] }, "lastUpdatedEpoch": { "type": "integer", "description": "Date when last updated. Epoch format.", "example": 1613677209722 }, "primaryId": { "type": "string", "description": "ID of the primary asset.", "format": "uuid", "example": "f81769d1-8e93-4af7-856e-56ea30ec1038" }, "relationshipId": { "type": "string", "format": "uuid", "description": "ID that defines relationship between primary and secondary assets.", "example": "f81769d1-8e93-4af7-856e-56ea30ab1038-73b49f17-4c1a-4c05-bb31-5ab2364e2534" } }, "description": "Describes relationship between two assets." }, "AssetRenditions": { "type": "object", "properties": { "width": { "type": "integer", "example": 4000 }, "imageThumb": { "type": "string", "example": "https://host.io/1571671854145/3a76743f-45f6-4d30-a7d4-05de2dc8c232/cc8f089a-1464-89d5-42f6-77217a9f09f2-200x200.png" }, "imagePreview": { "type": "string", "example": "https://host.io/1571671854145/3a76743f-45f6-4d30-a7d4-05de2dc8c232/cc8f089a-1464-42f6-89d5-77217a9f09f2-700x700.png" }, "fpo": { "type": "string", "example": "https://host.io/1571671854145/3a76743f-45f6-4d30-a7d4-05de2dc8c232/adventure-alps-beautiful-landscape-2444403-fpo.png" }, "imagePreviewLarge": { "type": "string", "example": "https://host.io/1571671854145/3a76743f-45f6-4d30-a7d4-05de2dc8c232/cc8f089a-1464-42f6-89d5-77217a9f09f2-1000x1000.png" }, "mezzaninePreview": { "type": "string", "example": "https://host.io/1571671854145/3a76743f-45f6-4d30-a7d4-05de2dc8c232/adventure-alps-beautiful-landscape-2444403-3000x3000.png" }, "height": { "type": "integer", "example": 6000 } }, "description": "Renditions details" }, "AssetShareSender": { "type": "object", "properties": { "name": { "type": "string", "description": "Sender's name", "example": "John" } }, "description": "Sender information to use in the email" }, "AssetTransformationObject": { "type": "object", "properties": { "objectId": { "type": "string", "description": "Object Id of the Asset", "format": "uuid", "example": "9f23f1d5-44c1-4b69-8f66-8f0fd03b62c7" }, "expiration": { "type": "integer", "description": "expiry of presigned url", "example": 3600 }, "source": { "type": "string", "description": "name of the rendition to be used in transformation", "example": "imagePreviewLarge" }, "includeOriginal": { "type": "boolean", "description": "Whether original asset should be included in result or not", "example": false }, "transformations": { "type": "string", "description": "Transformation name", "example": "png" } }, "description": "Sender information to use in the email" }, "AssetShareRecipient": { "type": "object", "properties": { "email": { "type": "string", "description": "Recipient's email", "format": "email" }, "name": { "type": "string", "description": "Recipient's name", "example": "Jeff" } }, "description": "Recipient information to use in the email" }, "AssetCreateLinkResponse": { "type": "array", "description": "Array of objects for every secondary id with the execution status.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetCreateLinkSuccessResponse" }, { "$ref": "#/components/schemas/AssetCreateLinkFailureResponse" } ] } }, "AssetCreateLinkSuccessResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Relationship created successfully" }, "relationshipId": { "type": "string", "format": "uuid", "example": "f81769d1-8e93-4af7-856e-56ea30ec1038-73b49f17-4c1a-4c05-bb31-5ab2364e25fe" } } }, "AssetCreateLinkFailureResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Item already exists" }, "relationshipId": { "type": "string", "format": "uuid", "example": "f81769d1-8e93-4af7-856e-56ea30ec1038-c91f8b40-a7ba-476c-b52f-341952f6c250" } } }, "AssetCreateValidationErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "INVALID_REQUEST" }, "details": { "type": "array", "description": "List of validation error messages describing why the Asset could not be created.", "items": { "type": "string" }, "example": [ "Failed to extract Filename or MimeType from Asset for Create Asset Object" ] } } }, "AssetSecurityDenormalized": { "type": "array", "items": { "$ref": "#/components/schemas/AssetSecurityDenormalizedObject" } }, "AssetSecurityDenormalizedObject": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" }, "permissions": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "d0bbfb23-9304-4eb0-9c60-8e6e27a580d9" } } } }, "AssetTechnicalMetadata": { "type": "object", "properties": { "tenovos_metadata": { "$ref": "#/components/schemas/TenovosMetadata" }, "image_metadata": { "$ref": "#/components/schemas/AssetImageMetadata" } }, "description": "Technical metadata about the asset" }, "AssetUpdateRequest": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/MetadataDocument" }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] } } }, "AssetReplacePreviewRequest": { "type": "object", "properties": { "fileIds": { "type": "array", "items": { "type": "string", "format": "uuid", "example": "7d6f4e30-f423-11e9-8071-89c0c4052141" } }, "filename": { "type": "string", "example": "Preview.jpg" }, "filesize": { "type": "integer", "example": 1024 }, "contentPaths": { "type": "object", "description": "This property is used only for federated assets", "example": { "imagePreview": "", "imageThumb": "", "videoProxy": "" } } } }, "AssetShareRequest": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/AssetShareSender" }, "shareUsers": { "type": "array", "description": "A list of users to share assets with", "items": { "$ref": "#/components/schemas/AssetShareRecipient" } }, "assets": { "type": "array", "description": "List of Asset object IDs to be shared", "items": { "type": "string", "format": "uuid" } }, "shareMessage": { "type": "string", "description": "An email message.", "example": "A message from sender to recipient" } } }, "AssetTransformRequest": { "type": "object", "properties": { "transformations": { "type": "array", "items": { "$ref": "#/components/schemas/AssetTransformationObject" } }, "recipients": { "type": "string", "description": "A list of emails of users to share assets with" }, "shareMessage": { "type": "string", "description": "An email message.", "example": "A message from sender to recipient" } } }, "AssetTransformResponse": { "type": "object", "properties": { "jobId": { "type": "string", "description": "Id of the Job created for the transformation", "format": "uuid", "example": "f8479fef-c389-4b15-9736-e5dd7b35d8d3" }, "status": { "type": "string", "description": "status of the request, success or failure", "example": "success" }, "message": { "type": "string", "example": "Message sent successfully" } } }, "AssetShareResponse": { "type": "object", "properties": { "message": { "type": "string", "description": "A human-readable message describing the result. May be empty on a successful share.", "example": "" }, "collectionId": { "type": "string", "format": "uuid", "description": "The identifier of the collection created for the shared assets.", "example": "56fab5f7-066a-4db8-aec2-9b9adcc75220" }, "statusCode": { "type": "string", "description": "The status code of the request, e.g. success or error.", "example": "success" }, "collectionUrl": { "type": "string", "format": "URL", "description": "The URL where the shared collection can be viewed.", "example": "https://pa.app.tenovos.io/#/collection/56fab5f7-066a-4db8-aec2-9b9adcc75220" }, "status": { "type": "string", "description": "status of the request, success or failure", "example": "success" } } }, "AssetReplacePreviewResponse": { "type": "array", "description": "An array of upload targets, one entry per file in the request. Upload the preview file via a PUT request to each pre-signed **url**.", "items": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the preview file to be uploaded.", "example": "Preview.jpg" }, "fileId": { "type": "string", "description": "The unique identifier assigned to the uploaded preview file.", "example": "b3b43fe0-17aa-4e0e-bbe3-b80c915f5508" }, "url": { "type": "string", "format": "URL", "description": "Pre-signed S3 URL used to upload the preview file via a PUT request. The URL expires after a limited time.", "example": "https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/preview/b3b43fe0-17aa-4e0e-bbe3-b80c915f5508/Preview.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260619%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260619T190544Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host" } } } }, "AuthRequest": { "type": "object", "properties": { "username": { "type": "string", "description": "Use in a **new token** request. Username of the user in Tenovos." }, "password": { "type": "string", "description": "Use in **new token** request. Valid password for the Tenovos user account." }, "session": { "$ref": "#/components/schemas/AuthRequest_session" } } }, "AuthExpireResponse": { "type": "object", "required": [ "endpointUrl", "clientId", "userPoolId", "username", "session" ], "properties": { "endpointUrl": { "type": "string", "format": "URL", "description": "The API's base URL.", "example": "https://endpoint.url/v1" }, "clientId": { "type": "string", "description": "The **clientId**. Available in the response of an Access Token generation request." }, "userPoolId": { "type": "string", "description": "The **Cognito Pool ID** of your Tenovos tenant." }, "username": { "type": "string", "format": "username", "description": "Use in a **new token** request. Username of the user in Tenovos." }, "session": { "$ref": "#/components/schemas/AuthExpireResponse_session" } } }, "AuthExpireRequest": { "type": "object", "required": [ "endpointUrl", "clientId", "userPoolId", "username", "session" ], "properties": { "endpointUrl": { "type": "string", "format": "URL", "description": "The API's base URL.", "example": "https://endpoint.url/v1" }, "clientId": { "type": "string", "description": "The **clientId**. Available in the response of an Access Token generation request." }, "userPoolId": { "type": "string", "description": "The **Cognito Pool ID** of your Tenovos tenant." }, "username": { "type": "string", "format": "username", "description": "Use in a **new token** request. Username of the user in Tenovos." }, "session": { "$ref": "#/components/schemas/AuthExpireRequest_session" } } }, "AuthResponse": { "type": "object", "properties": { "endpointUrl": { "type": "string", "example": "https://endpoint.url/v1" }, "clientId": { "type": "string", "example": "abcdefghijklmnop1234567890" }, "userPoolId": { "type": "string", "example": "us-east-1_123456789" }, "username": { "type": "string", "example": "username" }, "password": { "type": "string", "example": "" }, "session": { "$ref": "#/components/schemas/AuthResponse_session" } } }, "ImpersonateRequest": { "type": "object", "properties": { "username": { "type": "string", "description": "Use in **new token** request" } } }, "ImpersonateResponse": { "type": "object", "properties": { "endpointUrl": { "type": "string", "example": "https://endpoint.url/v1" }, "clientId": { "type": "string", "example": "abcdefghijklmnop1234567890" }, "userPoolId": { "type": "string", "example": "us-east-1_123456789" }, "username": { "type": "string", "example": "username" }, "password": { "type": "string", "example": "" }, "session": { "$ref": "#/components/schemas/ImpersonateResponse_session" } } }, "Collection": { "type": "object", "properties": { "expirationDate": { "type": "integer", "description": "Expiration date in milliseconds", "example": 1613755131855 }, "lastUpdatedEpoch": { "type": "integer", "description": "Last update time in milliseconds", "example": 1613755131855 }, "shareMessage": { "type": "string", "example": "" }, "recipients": { "type": "array", "items": { "type": "string" } }, "downloadId": { "type": "string", "example": "NULL" }, "shared": { "type": "string", "description": "Shared Collection Flag (Y | N)", "enum": [ "N", "Y" ] }, "name": { "type": "string", "description": "Collection Name", "example": "Best of the month" }, "shareDocument": { "type": "array", "description": "Array of Asset IDs for shared Collection", "items": { "type": "string", "format": "uuid" } }, "sender": { "type": "object" }, "createdEpoch": { "type": "integer", "description": "Creation time in milliseconds", "example": 1613755131855 }, "userCognitoId": { "type": "string", "description": "User ID who created this Collection", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c4052141" }, "collectionType": { "type": "string", "description": "Type of Collection (secured | private)", "enum": [ "secured", "private" ] }, "collectionId": { "type": "string", "description": "Collection ID", "format": "uuid", "example": "4dc328ce-4b3f-4f76-b7bb-1e83ad35458a" }, "collectionDocument": { "type": "array", "description": "Array of Asset IDs in Collection", "items": { "type": "string", "format": "uuid", "example": "0176c8e6-1017-4308-be3b-2de3931cbb37" } }, "customerId": { "type": "string", "description": "Customer ID", "example": "1235644566523" } } }, "CollectionCreateRequest": { "type": "object", "properties": { "collectionType": { "type": "string", "enum": [ "secured", "private" ] }, "name": { "type": "string", "description": "Name of the collection", "example": "Best of the month" }, "collectionDocument": { "type": "array", "description": "List of Asset IDs to be added to the Collection.", "items": { "type": "string", "description": "ID of the asset", "format": "uuid" } }, "metadataTemplateId": { "type": "string", "description": "Unique ID of the metadata template for 'secure' or 'private' collections", "format": "uuid", "example": "ea6eb24d-adef-4380-bd02-f64f567c437f" }, "securityTemplateIds": { "type": "array", "description": "List of Security Template IDs", "items": { "type": "string", "format": "uuid", "example": "7d6f4e30-f423-11e9-8071-89c0c4052156" } }, "metadataDocument": { "$ref": "#/components/schemas/MetadataDocument" } } }, "CollectionCreateResponse": { "type": "object", "properties": { "statusCode": { "type": "string", "example": "success", "enum": [ "success", "error" ] }, "message": { "type": "string", "description": "On success, this is a **JSON-encoded string** (not a plain message) containing the created Collection's details. When parsed, it contains:\n - **collectionId** (uuid) - ID of the created Collection\n - **collectionType** (string) - type of the Collection, e.g. `secured`\n - **asset** (string) - a further JSON-encoded string which, once parsed, contains **presignedurls**: an array of objects (`filename`, `filetype`, `objectId`, `fileId`, `originalFileId`, `url`) with presigned URLs to upload the Collection's cover image content.\n\nOn error, this is a plain human-readable error message.", "example": "Collection successfully created" }, "collectionId": { "type": "string", "description": "ID of created collection if successful", "format": "uuid", "example": "4b5896b4-33e4-41ac-b251-39a4dbaa25b1" } } }, "CollectionDeleteResponse": { "type": "object", "properties": { "status": { "type": "string", "description": "success if the Collection was deleted, error if the specified Collection ID does not exist", "enum": [ "success", "error" ], "example": "success" }, "message": { "type": "string", "example": "Collection delete operation succeeded" }, "collectionId": { "type": "string", "description": "Collection ID from the request", "format": "uuid", "example": "aaee01be-8ba4-49a7-8411-c5f3f4a84f45" } } }, "CollectionUpdateRequest": { "type": "object", "properties": { "collectionType": { "type": "string", "description": "Type of the collection.", "enum": [ "secured", "private" ] }, "name": { "type": "string", "description": "Name of the collection", "example": "Photo Collection" }, "collectionDocument": { "type": "array", "description": "List of fileIDs to be added to collection. This list will replace the current set of assets in the collection.", "items": { "type": "string", "format": "uuid" } } }, "description": "Updates specified properties of the collection. Only those properties that need to be updated should be specified." }, "CollectionUpdateResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "CollectionSearchItem": { "type": "object", "properties": { "collectionId": { "type": "string", "description": "Collection ID in UUID format", "format": "uuid", "example": "6c921f5c-24c2-40b9-8718-3ad2d4a6be54" }, "createdEpoch": { "type": "integer", "description": "Created date timestamp in milliseconds", "example": 1613773880176 }, "customerId": { "type": "string", "description": "Current User's Customer ID", "example": "1739271540099" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last update time in milliseconds", "example": 1613773880176 }, "collectionType": { "type": "string", "description": "Collection type either secured or privateSecured", "enum": [ "privateSecured", "secured" ] }, "name": { "type": "string", "description": "Name of the Collection", "example": "Pied Piper Brand Logo Kit" }, "shared": { "type": "string", "description": "Y/N is this Collection shareable or not", "enum": [ "Y", "N" ] }, "shareDocument": { "type": "array", "description": "List of share document IDs", "items": { "type": "string" } }, "userCognitoId": { "type": "string", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c4052141" }, "collectionDocument": { "type": "array", "description": "List of Asset Object IDs which are assigned to this Collection", "items": { "type": "string", "example": "58ab7b10-2c0a-4ff6-b9d4-098b4abd6175" } } } }, "CollectionSearchResult": { "type": "object", "properties": { "hitCount": { "type": "integer", "description": "Number of Collections returned in this response", "example": 2 }, "totalCount": { "type": "integer", "description": "Total number of Collections matching the search across all pages", "example": 2 }, "result": { "type": "array", "description": "List of Collection objects", "items": { "$ref": "#/components/schemas/CollectionSearchItem" } }, "facets": { "type": "array", "description": "Facet aggregations for the search result set", "items": { "type": "object" } } } }, "CollectionShareRequest": { "type": "object", "properties": { "sender": { "$ref": "#/components/schemas/Sender" }, "shareUsers": { "type": "array", "description": "A list of email addresses of the recipients.", "items": { "$ref": "#/components/schemas/Recipient" } }, "shareMessage": { "type": "string", "description": "A message from sender to recipient", "example": "A message from sender to recipient" } } }, "CollectionShareResponse": { "type": "object", "properties": { "StatusCode": { "type": "integer", "example": 200 }, "ExecutedVersion": { "type": "string", "example": "$LATEST" }, "Payload": { "type": "string", "example": "{\"statusCode\":200,\"body\":\"{\\\"message\\\":\\\"Message sent successfully\\\"}\",\"headers\":{\"content-type\":\"application/json\"}}" } } }, "ControlledVocabulary": { "type": "object", "properties": { "createdEpoch": { "type": "integer", "description": "Create time in milliseconds", "example": 1613877219787 }, "customerId": { "type": "string", "description": "Customer Id", "example": "157167185123342" }, "lastUpdatedEpoch": { "type": "integer", "description": "Update time in milliseconds", "example": 1613877219787 }, "metadataDefinitionId": { "type": "string", "description": "Field ID", "format": "uuid", "example": "6c921f5c-24c2-40b9-8718-3ad2d4a6be54" }, "metadataDefinitionName": { "type": "string", "description": "Field Name", "example": "Colors" }, "metadataDefinitionSearchField": { "type": "string", "description": "Map search field for this metadata definition", "example": "colors" }, "metadataDefinitionType": { "type": "string", "example": "controlledVocabulary" }, "metadata": { "$ref": "#/components/schemas/ControlledVocabulary_metadata" } } }, "ControlledVocabularyResponse": { "type": "object", "properties": { "createdEpoch": { "type": "integer", "description": "Create time in milliseconds", "example": 1613877219787 }, "customerId": { "type": "string", "description": "Customer Id", "example": "157167185123342" }, "lastUpdatedEpoch": { "type": "integer", "description": "Update time in milliseconds", "example": 1613877219787 }, "metadataDefinitionId": { "type": "string", "description": "Field ID", "format": "uuid", "example": "6c921f5c-24c2-40b9-8718-3ad2d4a6be54" }, "metadataDefinitionName": { "type": "string", "description": "Field Name", "example": "Colors" }, "metadataDefinitionSearchField": { "type": "string", "description": "Map search field for this metadata definition", "example": "colors" }, "metadataDefinitionType": { "type": "string", "example": "controlledVocabulary" }, "metadataDocument": { "$ref": "#/components/schemas/ControlledVocabulary_metadata" } } }, "ControlledVocabularyOperationResult": { "type": "object", "description": "The updated Controlled Vocabulary definition returned for a single update operation.", "properties": { "metadataDefinitionId": { "type": "string", "format": "uuid", "description": "Controlled Vocabulary (metadata definition) ID", "example": "83559f3a-93a8-4eba-a709-0bca6497450e" }, "metadataDefinitionName": { "type": "string", "description": "Controlled Vocabulary name", "example": "Hooli Employees" }, "metadataDefinitionSearchField": { "type": "string", "description": "Mapped search field for this metadata definition", "example": "hooli_employees" }, "metadataDefinitionType": { "type": "string", "description": "Metadata definition type", "example": "controlledVocabulary" }, "customerId": { "type": "string", "description": "Customer ID", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "ID of the user who created the Controlled Vocabulary", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "format": "int64", "description": "Create time in milliseconds", "example": 1781815426034 }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "ID of the user who last updated the Controlled Vocabulary", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "format": "int64", "description": "Update time in milliseconds", "example": 1781815985807 }, "metadataDocument": { "$ref": "#/components/schemas/ControlledVocabulary_metadata" }, "securityTemplateIds": { "type": "array", "description": "Security Template IDs associated with the Controlled Vocabulary", "items": { "type": "string", "format": "uuid" } } } }, "ControlledVocabularyUpdateResponse": { "type": "object", "description": "The response is a JSON object keyed by the operation(s) performed in the request. Each key — `name`, `add`, `update`, or `delete` — maps to the updated Controlled Vocabulary definition. When multiple operations are submitted in a single request, the response contains a key for each operation performed.", "properties": { "name": { "allOf": [ { "description": "Returned when the Controlled Vocabulary name is changed (`name` operation in the request)." }, { "$ref": "#/components/schemas/ControlledVocabularyOperationResult" } ] }, "add": { "allOf": [ { "description": "Returned when new values are added (`add` operation in the request)." }, { "$ref": "#/components/schemas/ControlledVocabularyOperationResult" } ] }, "update": { "allOf": [ { "description": "Returned when existing values are updated (`update` operation in the request)." }, { "$ref": "#/components/schemas/ControlledVocabularyOperationResult" } ] }, "delete": { "allOf": [ { "description": "Returned when values are deleted (`delete` operation in the request)." }, { "$ref": "#/components/schemas/ControlledVocabularyOperationResult" } ] } } }, "ControlledVocabularyCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "Vocabulary Name", "example": "Color List" }, "values": { "type": "array", "description": "List of vocabulary values", "example": [ "Red", "Blue" ], "items": { "type": "string" } } } }, "ControlledVocabularyUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "description": "New name of the Controlled Vocabulary", "example": "Hooli Employees" }, "add": { "type": "array", "description": "JSON Array with new values to add into the Controlled Vocabulary", "items": { "type": "string", "example": "Jared Dunn" } }, "update": { "type": "array", "description": "Payload to update existing values by their IDs", "example": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" } ], "items": { "$ref": "#/components/schemas/ControlledVocabularyUpdateRequest_update" } }, "delete": { "type": "array", "description": "JSON array with the value IDs to delete from Controlled Vocabulary", "items": { "type": "string", "example": "e1dd92fa-ed3a-4038-b837-c7f4d6395f16" } } } }, "ControlledVocabularyValue": { "type": "object", "properties": { "valueId": { "type": "string", "format": "uuid" }, "valueName": { "type": "string", "example": "Red" } } }, "DeleteResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Master Object update was successful" }, "data": { "type": "string", "description": "Serialized JSON representation of object's data", "example": "{\"lastUpdatedEpoch\":1613671028496,\"metadataTemplateId\":\"ea6eb24d-adef-4080-bd02-f64f567c437f\",\"createdBy\":\"7d675ef0-f423-11e9-8071-89c0c4052141\",\"originalFileId\":\"003391e4-e780-4186-b2d7-b5d4fcbe445d\",\"objectId\":\"e6f4bd5e-9bea-43cb-b15e-22582fa5d954\",\"renditionsDocument\":{\"fpo\":\"https://dev.content.tenovos.io/1571671854139/003391e4-e780-4186-b2d7-b5d4fcbe445d/animal-animal-photography-carnivore-2055100-fpo.png\",\"width\":2172,\"imagePreviewLarge\":\"https://dev.content.tenovos.io/1571671854139/003391e4-e780-4186-b2d7-b5d4fcbe445d/e5d61ed7-b859-493a-a7bb-eb89b0953b9f-1000x1000.png\",\"imageThumb\":\"https://dev.content.tenovos.io/1571671854139/003391e4-e780-4186-b2d7-b5d4fcbe445d/e5d61ed7-b859-493a-a7bb-eb89b0953b9f-200x200.png\",\"imagePreview\":\"https://dev.content.tenovos.io/1571671854139/003391e4-e780-4186-b2d7-b5d4fcbe445d/e5d61ed7-b859-493a-a7bb-eb89b0953b9f-700x700.png\",\"mezzaninePreview\":\"https://dev.content.tenovos.io/1571671854139/003391e4-e780-4186-b2d7-b5d4fcbe445d/animal-animal-photography-carnivore-2055100-3000x3000.png\",\"height\":3322},\"lockType\":[],\"fileId\":\"003391e4-e780-4186-b2d7-b5d4fcbe445d\",\"metadataDocument\":\"[{\\\"metadataDefinitionId\\\":\\\"dfeb57c1-b149-4b15-920f-3f40ff0b959a\\\",\\\"metadataDefinitionValue\\\":\\\"50MB51MB\\\"},{\\\"metadataDefinitionId\\\":\\\"b8cacda9-6ef8-4be6-a529-c1f5a18f0143\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"df04b9de-e79e-48ed-b9ba-019f14ba17a5\\\"}},{\\\"metadataDefinitionId\\\":\\\"8ea42d4f-1d93-4f29-81f8-aaf9de729f20\\\"},{\\\"metadataDefinitionId\\\":\\\"9234ed7f-0af4-4f47-97a0-0cef3dfba607\\\"},{\\\"metadataDefinitionId\\\":\\\"9b1688dd-fcf8-4507-bc5b-88f6bcfe48dd\\\",\\\"metadataDefinitionTableValue\\\":[[{\\\"metadataDefinitionId\\\":\\\"0303c809-d815-4865-97ba-b94c8f1e742b\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"273b4f2c-cc0c-4290-bd47-2360a30ae7c4\\\"}}],[{\\\"metadataDefinitionId\\\":\\\"0303c809-d815-4865-97ba-b94c8f1e742b\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"23fdd209-f51f-46a8-a64c-6272a79400a9\\\"}}]]},{\\\"metadataDefinitionId\\\":\\\"c8c719ed-f729-4569-b50a-c5e10fd32b23\\\",\\\"metadataDefinitionTableValue\\\":[[{\\\"metadataDefinitionId\\\":\\\"15be99d0-1241-44d9-b359-6e99332ed962\\\",\\\"metadataDefinitionValue\\\":[{\\\"metadataDefinitionId\\\":\\\"db42dfa4-35f7-4242-9b0c-ff8dc6cdab8f\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"aeea73dd-2337-4e92-911e-83b4a0e7897c\\\"}},{\\\"metadataDefinitionId\\\":\\\"1de0dfa6-2a97-4031-8e3b-ca9487f459b7\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"19b9e829-f578-4379-8fd0-f43aff663e53\\\"}}]}]]},{\\\"metadataDefinitionId\\\":\\\"97de4763-684e-410e-bf79-414ec4b35608\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"445b691c-9a76-4800-a720-e99cf8e46230\\\"}},{\\\"metadataDefinitionId\\\":\\\"dc50d092-182b-49c2-ae64-b1ba561fe6d6\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"241189e9-420c-4f28-8ddf-72c542d4c3b9\\\"}},{\\\"metadataDefinitionId\\\":\\\"97a64a6c-50d6-406e-9473-79b3819b03e7\\\",\\\"metadataDefinitionTableValue\\\":[[{\\\"metadataDefinitionId\\\":\\\"2017f4ff-f40f-4f71-9f38-45887225ea59\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"053358d0-7663-4d05-b3f2-cbd1ed1a2225\\\"}},{\\\"metadataDefinitionId\\\":\\\"4e30aa55-3870-424c-b456-c1131110cd1b\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"fb3d0ddd-50c2-48cf-a291-7bd38ebec643\\\"}},{\\\"metadataDefinitionId\\\":\\\"3229e863-022b-4365-afe6-e9aa3807c386\\\",\\\"metadataDefinitionValue\\\":\\\"02/10/2021\\\"},{\\\"metadataDefinitionId\\\":\\\"9b51b9e2-0815-4f01-b63c-d13f75383746\\\",\\\"metadataDefinitionValue\\\":\\\"02/18/2021\\\"}]]},{\\\"metadataDefinitionId\\\":\\\"5de1238d-a703-4da3-aa2b-60a6a1c7cf2f\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"ea6eb24d-adef-4080-bd02-f64f567c437f\\\"}},{\\\"metadataDefinitionId\\\":\\\"68a7fcc6-090e-4b7f-920d-be0dbddb1ff3\\\",\\\"metadataDefinitionValue\\\":[{\\\"valueId\\\":\\\"7d6f4e30-f423-11e9-8071-89c0c4052141\\\"}]},{\\\"metadataDefinitionId\\\":\\\"721ff851-13cc-48fe-bc4b-3927d36450d4\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"7d675ef0-f423-11e9-8071-89c0c4052141\\\"}},{\\\"metadataDefinitionId\\\":\\\"2b2a54d7-1898-44f5-a0f5-bd56fa4a7485\\\",\\\"metadataDefinitionValue\\\":\\\"1608745510614\\\"},{\\\"metadataDefinitionId\\\":\\\"baedc7de-c79e-4f4f-8648-1b19737a30ed\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"8157e90c-90f4-4537-9935-1a3bf011a526\\\"}},{\\\"metadataDefinitionId\\\":\\\"e3667a6f-1e09-4afb-85ee-0a5c2174d4f0\\\",\\\"metadataDefinitionValue\\\":{\\\"valueId\\\":\\\"0de14dd8-7d39-466a-a8a9-9f35ab722cac\\\"}}]\",\"metadataDeletedEpoch\":1613671241253,\"technicalMetadataDocument\":\"{\\\"tenovos_metadata\\\":{\\\"fileName\\\":\\\"animal-animal-photography-carnivore-2055100.jpg\\\",\\\"fileSize\\\":\\\"940 kB\\\",\\\"MD5Checksum\\\":\\\"b746d0fbffcbace4841709039b1f53ae\\\"},\\\"image_metadata\\\":{\\\"fileName\\\":\\\"animal-animal-photography-carnivore-2055100.jpg\\\",\\\"fileSize\\\":\\\"940 kB\\\",\\\"fileType\\\":\\\"JPEG\\\",\\\"fileTypeExtension\\\":\\\"jpg\\\",\\\"mimeType\\\":\\\"image/jpeg\\\",\\\"jfifVersion\\\":1.01,\\\"resolutionUnit\\\":\\\"inches\\\",\\\"xResolution\\\":72,\\\"yResolution\\\":72,\\\"profileCMMType\\\":\\\"Linotronic\\\",\\\"profileVersion\\\":\\\"2.1.0\\\",\\\"profileClass\\\":\\\"Display Device Profile\\\",\\\"colorSpaceData\\\":\\\"RGB\\\",\\\"profileConnectionSpace\\\":\\\"XYZ\\\",\\\"profileDateTime\\\":\\\"1998:02:09 06:49:00\\\",\\\"profileFileSignature\\\":\\\"acsp\\\",\\\"primaryPlatform\\\":\\\"Microsoft Corporation\\\",\\\"cmmFlags\\\":\\\"Not Embedded, Independent\\\",\\\"deviceManufacturer\\\":\\\"Hewlett-Packard\\\",\\\"deviceModel\\\":\\\"sRGB\\\",\\\"deviceAttributes\\\":\\\"Reflective, Glossy, Positive, Color\\\",\\\"renderingIntent\\\":\\\"Perceptual\\\",\\\"connectionSpaceIlluminant\\\":\\\"0.9642 1 0.82491\\\",\\\"profileCreator\\\":\\\"Hewlett-Packard\\\",\\\"profileID\\\":\\\"0\\\",\\\"profileCopyright\\\":\\\"Copyright (c) 1998 Hewlett-Packard Company\\\",\\\"profileDescription\\\":\\\"sRGB IEC61966-2.1\\\",\\\"mediaWhitePoint\\\":\\\"0.95045 1 1.08905\\\",\\\"mediaBlackPoint\\\":\\\"0 0 0\\\",\\\"redMatrixColumn\\\":\\\"0.43607 0.22249 0.01392\\\",\\\"greenMatrixColumn\\\":\\\"0.38515 0.71687 0.09708\\\",\\\"blueMatrixColumn\\\":\\\"0.14307 0.06061 0.7141\\\",\\\"deviceMfgDesc\\\":\\\"IEC http://www.iec.ch\\\",\\\"deviceModelDesc\\\":\\\"IEC 61966-2.1 Default RGB color space - sRGB\\\",\\\"viewingCondDesc\\\":\\\"Reference Viewing Condition in IEC61966-2.1\\\",\\\"viewingCondIlluminant\\\":\\\"19.6445 20.3718 16.8089\\\",\\\"viewingCondSurround\\\":\\\"3.92889 4.07439 3.36179\\\",\\\"viewingCondIlluminantType\\\":\\\"D50\\\",\\\"luminance\\\":\\\"76.03647 80 87.12462\\\",\\\"measurementObserver\\\":\\\"CIE 1931\\\",\\\"measurementBacking\\\":\\\"0 0 0\\\",\\\"measurementGeometry\\\":\\\"Unknown\\\",\\\"measurementFlare\\\":\\\"0.999%\\\",\\\"measurementIlluminant\\\":\\\"D65\\\",\\\"technology\\\":\\\"Cathode Ray Tube Display\\\",\\\"redToneReproductionCurve\\\":\\\"(Binary data 2060 bytes, use -b option to extract)\\\",\\\"greenToneReproductionCurve\\\":\\\"(Binary data 2060 bytes, use -b option to extract)\\\",\\\"blueToneReproductionCurve\\\":\\\"(Binary data 2060 bytes, use -b option to extract)\\\",\\\"imageWidth\\\":2172,\\\"imageHeight\\\":3322,\\\"encodingProcess\\\":\\\"Baseline DCT, Huffman coding\\\",\\\"bitsPerSample\\\":8,\\\"colorComponents\\\":3,\\\"yCbCrSubSampling\\\":\\\"YCbCr4:2:0 (2 2)\\\",\\\"imageSize\\\":\\\"2172x3322\\\",\\\"megapixels\\\":7.2}}\",\"AITags\":[],\"lastUpdatedBy\":\"7d675ef0-f423-11e9-8071-89c0c4052141\",\"metadataState\":\"recycle bin\",\"objectType\":\"Asset\",\"securityTemplateIds\":[\"7d6f4e30-f423-11e9-8071-89c0c4052141\"],\"fileDeletedBy\":\"7d675ef0-f423-11e9-8071-89c0c4052141\",\"metadataDeletedBy\":\"7d675ef0-f423-11e9-8071-89c0c4052141\",\"currentVersion\":\"N\",\"versionNumber\":1608745510614,\"filename\":\"animal-animal-photography-carnivore-2055100.jpg\",\"lockStatus\":\"unlocked\",\"createdEpoch\":1608745510614,\"childProductIds\":[],\"digitalAssetIds\":[],\"customerId\":\"1571671854139\",\"fileState\":\"recycle bin\",\"fileDeletedEpoch\":1613671241253}" } } }, "ErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Detailed Error Message" } } }, "GeneralResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Detailed Message" } } }, "GeneralErrorMessageResponse": { "type": "object", "properties": { "message": { "type": "string" }, "detail": { "type": "string" } } }, "GroupPermission": { "type": "object", "properties": { "permissionId": { "type": "string", "format": "uuid", "example": "d0bbfb23-9304-4eb0-9c60-8e6e27a580d9" }, "isPermitted": { "type": "boolean", "example": true } } }, "GeneralErrorResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "error" }, "message": { "type": "string", "example": "Detailed Message" } } }, "GetProofReviewerUrlRequest": { "type": "object", "properties": { "email": { "type": "string", "description": "Email of user who wishes to access proof (must have permission).", "format": "email", "example": "john@company.com" } } }, "GetProofReviewerUrlResponse": { "type": "object", "properties": { "url": { "type": "string", "description": "URL of proof corresponding to ID.", "format": "website URL" } } }, "MetadataAttribute": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute." }, "name": { "type": "string", "description": "Name of the attribute.", "example": "Product Name" }, "type": { "type": "string", "description": "Attribute type.", "enum": [ "controlledVocabulary", "date", "text", "tableAttribute", "cascadeAttribute", "externalContent" ] }, "subType": { "type": "string", "description": "Sub-type for text attributes.", "enum": [ "textBox", "textArea" ] }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "product_name" }, "attributeOrder": { "type": "integer", "description": "Display order of attribute in this group.", "example": 1 }, "fieldOrder": { "type": "integer", "description": "Display order within a table (for table fields only)." }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "required": { "type": "boolean", "description": "Whether the attribute is required.", "example": false }, "readonly": { "type": "boolean", "description": "Whether the attribute is read-only.", "example": false }, "facetable": { "type": "boolean", "description": "Whether the attribute can be used as a search facet.", "example": true }, "sensitive": { "type": "boolean", "description": "Whether the attribute contains sensitive data.", "example": false }, "typeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled.", "example": false }, "featured": { "type": "boolean", "description": "Whether the attribute is featured.", "example": false }, "isRestricted": { "type": "boolean", "description": "Whether the attribute is restricted.", "example": false }, "isMultipleSelect": { "type": "boolean", "description": "Whether multi-select is enabled (for controlledVocabulary).", "example": false }, "sortByHitCount": { "type": "boolean", "description": "Whether results are sorted by hit count.", "example": false }, "dateFormat": { "type": "string", "description": "Date format string. \"N/A\" for non-date attributes.", "example": "N/A" }, "length": { "type": "integer", "description": "Maximum character length (for text attributes).", "example": 100 }, "tooltip": { "type": "string", "description": "Tooltip helper text.", "example": "" }, "techMetaMapping": { "type": "string", "description": "Technical metadata mapping configuration. Empty string if none.", "example": "" }, "controlledVocabularyId": { "type": "string", "format": "uuid", "description": "ID of the associated controlled vocabulary (for controlledVocabulary type).", "example": "34abed31-4546-4f15-ae07-3d22b9b056d5" }, "isSingleRow": { "type": "boolean", "description": "Whether the table is single-row only (for tableAttribute)." }, "isSmartTable": { "type": "boolean", "description": "Whether the table is a smart table (for tableAttribute)." }, "tableNameVisible": { "type": "boolean", "description": "Whether the table name is visible (for tableAttribute)." }, "tableFieldsDenormalized": { "type": "array", "description": "Denormalized fields within a table attribute. Each field follows the same attribute schema.", "items": { "$ref": "#/components/schemas/MetadataAttribute" } }, "cascadeMapId": { "type": "string", "format": "uuid", "description": "ID of the cascade map (for cascadeAttribute)." }, "cascadeNameVisible": { "type": "boolean", "description": "Whether the cascade name is visible (for cascadeAttribute)." }, "cascadeOrder": { "type": "integer", "description": "Order within a cascade (for cascade fields)." }, "cascadeFieldsDenormalized": { "type": "array", "description": "Denormalized fields within a cascade attribute.", "items": { "$ref": "#/components/schemas/MetadataAttribute" } } }, "description": "Object that describes a metadata attribute. Fields present vary by `type`." }, "MetadataApplyResponse": { "type": "object", "properties": { "message": { "type": "string", "example": "Changes applied successfully" } } }, "MetadataDocument": { "type": "array", "description": "Array of metadata attributes", "items": { "anyOf": [ { "$ref": "#/components/schemas/MetadataStringValue" }, { "$ref": "#/components/schemas/MetadataRestrictedVocabularyValue" }, { "$ref": "#/components/schemas/MetadataDateValue" }, { "$ref": "#/components/schemas/MetadataMultiValue" }, { "$ref": "#/components/schemas/MetadataGridValue" } ] } }, "MetadataStringValue": { "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "dfeb57c1-b149-4b15-920f-3f40ff0b959a" }, "metadataDefinitionValue": { "type": "string", "example": "Photo" } }, "description": "Defines a text attribute" }, "MetadataDateValue": { "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionValue": { "type": "string", "description": "Date formatted as **mm/dd/yyyy** string", "example": "02/10/2021" } }, "description": "Defines a date attribute" }, "MetadataRestrictedVocabularyValue": { "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid" }, "metadataDefinitionValue": { "$ref": "#/components/schemas/AssetBulkEditRestrictedVocabularyValue_metadataDefinitionValue" } }, "description": "Defines a Restricted Vocabulary attribute" }, "MetadataMultiValue": { "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionValue": { "type": "array", "description": "An array of values.", "items": { "$ref": "#/components/schemas/AssetBulkEditMultiValue_metadataDefinitionValue" } } }, "description": "Defines a multi-select attribute" }, "MetadataGridValue": { "type": "object", "properties": { "metadataDefinitionId": { "type": "string", "description": "Definition ID", "format": "uuid", "example": "3229e863-022b-4365-afe6-e9aa3807c386" }, "metadataDefinitionTableValue": { "type": "array", "description": "Array representing the rows in the grid.", "items": { "$ref": "#/components/schemas/MetadataTableRow" } } }, "description": "Defines a table" }, "MetadataTableRow": { "type": "array", "description": "Array defining the columns of the grid.", "items": { "anyOf": [ { "$ref": "#/components/schemas/MetadataStringValue" }, { "$ref": "#/components/schemas/MetadataRestrictedVocabularyValue" }, { "$ref": "#/components/schemas/MetadataDateValue" } ] } }, "MetadataGroup": { "type": "object", "properties": { "groupOrder": { "type": "integer", "description": "Display order of this group." }, "metadataGroupName": { "type": "string", "description": "Group name." }, "metadataGroupSearchField": { "type": "string", "description": "System-generated slug for the group." }, "securityPermissions": { "type": "array", "description": "Security permissions applied to this group. Empty array if none.", "items": { "type": "object" } }, "metadataAttributes": { "type": "array", "description": "List of this group's attributes. The shape of each attribute varies by `type`:\n- **text** (subType: textBox) — includes `length`, `typeahead`, `techMetaMapping`. Max 250 chars, supports faceting.\n- **text** (subType: textArea) — includes `length`, `techMetaMapping`. Max 10000 chars. Cannot be facetable or typeahead.\n- **controlledVocabulary** — includes `controlledVocabularyId`, `isMultipleSelect`\n- **date** — includes `dateFormat`\n- **tableAttribute** — includes `tableFieldsDenormalized`, `isSingleRow`, `isSmartTable`, `tableNameVisible`\n- **cascadeAttribute** — includes `cascadeMapId`, `cascadeFieldsDenormalized`, `cascadeNameVisible`", "items": { "oneOf": [ { "$ref": "#/components/schemas/template-attribute-text" }, { "$ref": "#/components/schemas/template-attribute-controlled-vocabulary" }, { "$ref": "#/components/schemas/template-attribute-date" }, { "$ref": "#/components/schemas/template-attribute-table" }, { "$ref": "#/components/schemas/template-attribute-cascade" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/template-attribute-text", "controlledVocabulary": "#/components/schemas/template-attribute-controlled-vocabulary", "date": "#/components/schemas/template-attribute-date", "tableAttribute": "#/components/schemas/template-attribute-table", "cascadeAttribute": "#/components/schemas/template-attribute-cascade" } } } } } }, "MetadataTemplate": { "type": "object", "properties": { "template": { "$ref": "#/components/schemas/MetadataTemplate_template" } } }, "ProofUserRoles": { "type": "string", "enum": [ "manager", "user", "guest" ] }, "MetadataTemplateType": { "type": "string", "enum": [ "default", "action", "search", "proof", "tile" ] }, "ProofStatusResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "completed" }, "decisionStatus": { "type": "string", "example": "approved" } } }, "Recipient": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "example": "john@mail.com" }, "name": { "type": "string", "example": "John" } } }, "RelationshipCreateRequest": { "type": "object", "properties": { "secondaryIds": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipCreateRequest_secondaryIds" } } } }, "RelationshipDeleteRequest": { "type": "object", "properties": { "secondaryIds": { "type": "array", "items": { "$ref": "#/components/schemas/RelationshipDeleteRequest_secondaryIds" } } } }, "Search": { "type": "object", "properties": { "from": { "type": "integer", "description": "Search offset from which index search will start", "example": 0 }, "searchTerm": { "type": "array", "description": "List of search terms with AND operation be default", "items": { "type": "string", "example": "*" } }, "filters": { "type": "array", "description": "List of facet-style filter attributes and values, applied in addition to any `searchTerm` entries. Uses the same `(Attribute Name:\"Value\")` syntax as `searchTerm`, including the `-` prefix to exclude Assets matching a value. For example `(Asset Type:-\"Logo\")` returns Assets that do **not** have an Asset Type of Logo, while `(Asset Type:\"Logo\")` returns only Assets that do.", "items": { "type": "string", "example": "(Asset Type:\"Logo\")" } }, "includeDeleted": { "type": "boolean", "description": "Flag to denote whether or not to include Deleted assets in the result", "items": { "type": "boolean", "example": true } }, "includeVersions": { "type": "boolean", "description": "Flag to denote whether or not to include prior versions of the asset in the result", "items": { "type": "boolean", "example": false } }, "sortBy": { "type": "array", "items": { "$ref": "#/components/schemas/Search_sortBy" } }, "operation": { "type": "string", "description": "Operation applied between search terms. `AND` requires all terms to match, `OR` matches any term, and `ANY` returns Collections matching any of the provided terms.", "example": "AND", "enum": [ "AND", "OR", "ANY" ] }, "aggregations": { "type": "boolean", "description": "Boolean field to indicate whether or not to return filter menu aggregation counts for the search term. Set to false to significant improve speed and reduce payload size.", "example": false }, "keywordSearchField": { "type": "string", "description": "Specified Search Target. Valid values are - filename, assetId, metadata, content", "example": "filename", "enum": [ "filename", "assetId", "metadata", "content" ] } } }, "Scan": { "type": "object", "properties": { "limit": { "type": "integer", "description": "Number of results that will be returned for each page", "example": 100 }, "searchTerm": { "type": "array", "description": "List of search terms", "items": { "type": "string", "example": "*" } }, "includeDeleted": { "type": "boolean", "description": "Flag to denote whether or not to include Deleted assets in the result", "items": { "type": "boolean", "example": true } }, "includeVersions": { "type": "boolean", "description": "Flag to denote whether or not to include prior versions of the asset in the result", "items": { "type": "boolean", "example": false } }, "sortBy": { "type": "array", "items": { "$ref": "#/components/schemas/Search_sortBy" } }, "operation": { "type": "string", "description": "Operation between search terms", "example": "AND", "enum": [ "AND", "OR" ] }, "keywordSearchField": { "type": "string", "description": "Specified Search Terms" }, "cursor": { "type": "string", "description": "Optional parameter on the first call. On subsequent calls requires the cursor value returned in the API response.", "example": "WzE2ODI5NTczMDM2NDgsMTY4Mjk1NzI2MzU5NSwxNjgyOTU3MjYzNTk1LCI3ZDkwZTkzMi01MmU4LTQ2NTEtYmQ3Ny03M2Y1OWFjMmY3YTMiLDEyMDI1OTA4NTEzMF0=" }, "assetType": { "type": "string", "description": "Optional parameter that restricts search results to the asset type specified.", "example": "Base Product" } } }, "SearchFacetList": { "type": "array", "items": { "$ref": "#/components/schemas/SearchFacetList_inner" } }, "ScanResult": { "type": "object", "properties": { "hitCount": { "type": "integer", "description": "Number of Assets return", "example": 1 }, "cursor": { "type": "string", "description": "Cursor returned after the first call to be passed on all subsequent calls to get the next page of results", "example": "WzE2ODI5NTczMDM2NDgsMTY4Mjk1NzI2MzU5NSwxNjgyOTU3MjYzNTk1LCI3ZDkwZTkzMi01MmU4LTQ2NTEtYmQ3Ny03M2Y1OWFjMmY3YTMiLDEyMDI1OTA4NTEzMF0=" }, "result": { "type": "array", "description": "List of Asset objects", "items": { "$ref": "#/components/schemas/Asset" } }, "facets": { "$ref": "#/components/schemas/SearchFacetList" } } }, "SearchResult": { "type": "object", "properties": { "hitCount": { "type": "integer", "description": "Number of Assets return", "example": 1 }, "result": { "type": "array", "description": "List of Asset objects", "items": { "$ref": "#/components/schemas/Asset" } }, "facets": { "$ref": "#/components/schemas/SearchFacetList" } } }, "SecurityGroups": { "type": "object", "properties": { "securityGroups": { "type": "array", "description": "Array of security groups", "items": { "type": "object", "properties": { "groupId": { "type": "string", "description": "Group ID of the User Group", "format": "uuid", "example": "e013bf7a-9702-406b-8d23-1bba004c88d4" }, "groupName": { "type": "string", "description": "The name of the User Group associated to the Group ID", "example": "EMEA Marketing" } } } } } }, "SecurityTemplate": { "type": "object", "properties": { "templateId": { "type": "string", "description": "Template ID", "format": "uuid", "example": "7d7345d0-f423-11e9-8071-89c0c4052141" }, "templateName": { "type": "string", "description": "TemplateName", "example": "No Access" }, "securityDenormalized": { "$ref": "#/components/schemas/AssetSecurityDenormalized" }, "templateDocument": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateDocument" } } } }, "Sender": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the person ton display in the email", "example": "Michael Lee" } } }, "StringErrorResponse": { "type": "string" }, "TemplateDocument": { "type": "object", "properties": { "groupPermissions": { "type": "array", "items": { "$ref": "#/components/schemas/GroupPermission" } }, "groupId": { "type": "string", "format": "uuid", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" } } }, "TenovosMetadata": { "type": "object", "properties": { "fileName": { "type": "string", "example": "adventure-alps-beautiful-landscape-2444403.jpg" }, "fileSize": { "type": "string", "example": "4.4 MB" }, "MD5Checksum": { "type": "string", "example": "6cbc612262877e8502904ea3ffd6a278" } }, "description": "Core technical metadata" }, "UpdateAssetResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "Asset update was successful" } } }, "User": { "type": "object", "properties": { "userId": { "type": "string", "description": "Current User ID", "format": "uuid", "example": "7d675ef0-f423-11e9-8071-89c0c4052141" }, "customerId": { "type": "string", "description": "Parent Customer ID", "example": "1234567890" }, "emailId": { "type": "string", "description": "User email", "format": "email", "example": "erlich.bachman@piedpiper.com" }, "firstName": { "type": "string", "description": "User first name", "example": "Erlich" }, "lastName": { "type": "string", "description": "User last name", "example": "Bachman" }, "roleId": { "type": "string", "description": "User role ID", "format": "uuid", "example": "7d5620e0-f423-11e9-8071-89c0c4052141" }, "status": { "type": "string", "description": "User account status", "example": "enabled" }, "groups": { "type": "array", "description": "List of group IDs that user belongs to", "items": { "type": "string", "format": "uuid", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" } }, "userName": { "type": "string", "nullable": true, "description": "The username of the Tenovos user, created by the Administrator or user at the time of account creation. Can be null for federated user accounts.", "example": "erlich.bachman" }, "phone": { "type": "string", "format": "phone", "example": 15551234565 }, "contact": { "type": "string", "description": "The person designated as the sponsor/point of contact for this user", "example": "Richard Hendricks" }, "country": { "type": "string", "description": "The country in which the Tenovos user is located.", "example": "USA" }, "company": { "type": "string", "description": "The company that the Tenovos user works for.", "example": "Pied Piper" }, "friendlyName": { "type": "string", "description": "A \"friendlier\" version of the username. Used in the UI display and provided by the user.", "example": "Erlich Bachman" } } }, "UserSavedSearches": { "type": "object", "properties": { "status": { "type": "string", "description": "Result of the API request", "example": "success" }, "data": { "type": "array", "description": "List of Saved Search objects", "items": { "$ref": "#/components/schemas/SavedSearches" } } } }, "SavedSearches": { "type": "object", "properties": { "searchId": { "type": "string", "description": "Saved Search ID in UUID format", "example": "6c921f5c-24c2-40b9-8718-3ad2d4a6be54" }, "searchTitle": { "type": "string", "description": "Name of the Saved Search", "example": "Hooli Products 2026" }, "searchDocument": { "type": "object", "description": "Details of the saved search", "properties": { "searchTitle": { "type": "string", "description": "Name of the Saved Search", "example": "Hooli Products 2026" }, "tags": { "type": "array", "description": "List of Search Terms passed in the search", "items": { "type": "string" }, "example": [ "Gilfoyle", "Dinesh", "Erlich" ] }, "createdEpoch": { "type": "integer", "description": "Epoch value when the saved search was created", "example": 1773161069216 }, "facetFilters": { "type": "array", "description": "List of Search Terms passed in the search", "items": { "type": "string" }, "example": [ "(System Created Date:\"1774508400000__1774594799999\")", "(Asset Type:\"Logo\" OR Asset Type:\"Graphic\")" ] }, "route": { "type": "string", "description": "View from which the saved search was created from.", "example": "gallery" }, "matchAny": { "type": "boolean", "description": "Determines the status of the 'AND'/'OR' toggle at the time of search creation. Match Any will be false if the toggle is set to 'AND'. Match Any will be true if the toggle is set to 'OR'.", "example": false }, "type": { "type": "string", "description": "Determines whether the search is a private or shared search", "enum": [ "private", "shared" ], "example": "shared" }, "includeVersions": { "type": "boolean", "description": "Determines if this search includes non-current versions in the result set.", "example": false }, "searchKeywordField": { "type": "string", "description": "Specified Search Target", "enum": [ "filename", "metadata", "content", "assetId" ], "example": "filename" }, "sortBy": { "type": "string", "description": "Field the search results are sorted by", "example": "createdEpoch" } } } } }, "UserUpdateSecurityGroupRequest": { "type": "object", "properties": { "userGroupId": { "type": "string", "description": "group-id of a valid existing user-security-group of customer", "format": "uuid", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" }, "userGroupName": { "type": "string", "description": "group-name of a valid existing user-security-group of a customer" } } }, "UserCreateRequest": { "required": [ "firstName", "lastName", "friendlyName", "email", "username", "password", "accountType", "userRoleId", "groups" ], "type": "object", "properties": { "firstName": { "type": "string", "description": "First Name of the User.", "minLength": 1, "maxLength": 50, "example": "John" }, "lastName": { "type": "string", "description": "Last Name of the User.", "minLength": 1, "maxLength": 50, "example": "Wick" }, "friendlyName": { "type": "string", "description": "Friendly Name of the User.", "minLength": 1, "maxLength": 50, "example": "john.wick" }, "email": { "type": "string", "description": "Email of the User.", "format": "email", "minLength": 6, "maxLength": 75, "example": "john.wick@tenovos.com" }, "username": { "type": "string", "format": "username", "minLength": 1, "maxLength": 50, "description": "Username of the User.", "example": "john.wick" }, "password": { "type": "string", "format": "password", "minLength": 8, "maxLength": 150, "description": "Password of the User.", "example": "sdhg&uuUz78u" }, "accountType": { "type": "string", "description": "Account Type of the User. Local accounts use a password; Federated accounts use an SSO service.", "example": "local", "enum": [ "local", "federated" ] }, "customAttributes": { "$ref": "#/components/schemas/UserCreateRequest_customAttributes" }, "userRoleId": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "description": "ID of the User's role. Only one role is allowed.", "example": "1401df5e-3f13-4c88-a5a8-de64f6227a03" }, "groups": { "type": "array", "minLength": 1, "description": "List of group IDs the User belongs to. At least one group is required.", "items": { "type": "string", "format": "uuid", "minLength": 36, "maxLength": 36, "example": "7d6207c0-f423-11e9-8071-89c0c4052141" } }, "isVerified": { "type": "boolean", "description": "Optional flag indicating whether the user account is verified upon creation. This is only supported for customers using Auth0 authentication.", "example": true } } }, "UserResponse": { "type": "object", "properties": { "roleId": { "type": "string", "description": "User role ID", "format": "uuid", "example": "7d5620e0-f423-11e9-8071-89c0c4052141" }, "status": { "type": "string", "description": "User account status", "example": "success" } } }, "UserSearchResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "data": { "type": "array", "description": "List of User objects", "items": { "$ref": "#/components/schemas/User" } } } }, "UserUpdateRequest": { "type": "object", "properties": { "firstName": { "type": "string", "description": "First Name of the user", "example": "John" }, "lastName": { "type": "string", "description": "Last Name of the user", "example": "Smith" }, "friendlyName": { "type": "string", "description": "Last Name of the user", "example": "John Smith" }, "email": { "type": "string", "description": "Email of the user", "example": "john.smith@company.com" }, "company": { "type": "string", "description": "Company name of the user", "example": "John's Company Inc." }, "country": { "type": "string", "description": "Country of the user", "example": "USA" }, "contact": { "type": "number", "description": "Contact Number of the user", "example": 1234567890 }, "phone": { "type": "number", "description": "Alternate phone number of the user", "example": 1234567890 }, "userRoleId": { "type": "string", "description": "User role id of the user", "format": "uuid", "example": "7d5620e0-f423-11e9-8071-89c0c4052141" }, "userRoleName": { "type": "string", "description": "User role name of the user", "example": "End user" }, "groups": { "type": "array", "description": "List of user group ids the user is part of", "items": { "type": "string", "description": "User group id", "format": "uuid", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" } }, "status": { "type": "string", "description": "Allows updating the users status to either enable or disabled. These values are case sensitive.", "example": "enabled", "enum": [ "enabled", "disabled" ] } } }, "UserUpdateSecurityGroupResponse": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "User Profile update was successful" } } }, "VocabularyDeleteErrorResponse": { "type": "object", "properties": { "message": { "type": "string" } } }, "WorkflowTemplateResponse": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowTemplate" } }, "WorkflowTemplate": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string", "example": "Marketing" } } }, "AssetBulkEditMultiValue_metadataDefinitionValue": { "type": "object", "properties": { "valueId": { "type": "string", "example": "7d6f4e30-f423-11e9-8071-89c0c4052141" } } }, "AssetBulkEditRestrictedVocabularyValue_metadataDefinitionValue": { "type": "object", "properties": { "valueId": { "type": "string", "format": "uuid" } } }, "AssetExposeRequest_inner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The Asset Object ID or the File ID of the asset.", "example": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "identifier": { "type": "string", "description": "Type of identifier", "example": "objectId", "enum": [ "objectId", "fileId" ] }, "components": { "type": "array", "description": "Array of Objects for generating urls based on properties rendition or object with expiration time in seconds.", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetExposeRefRendition" }, { "$ref": "#/components/schemas/AssetExposeRefObject" } ] } } } }, "AssetExposeResponse_inner": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "identifier": { "type": "string", "example": "objectId", "enum": [ "objectId", "fileId" ] }, "components": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/AssetExposeRenditionResponse" }, { "$ref": "#/components/schemas/AssetExposeObjectResponse" } ] } } } }, "AssetMultipartUploadRequest_parts": { "type": "object", "properties": { "partNumber": { "type": "number", "example": 1 }, "etag": { "type": "string", "description": "The ETag value returned in the response headers after uploading this part via a PUT request to its presigned URL. Must be provided for each uploaded part when completing the multipart upload.", "example": "6988d46a133c76f49c555deebb8efb8a" } } }, "AuthRequest_session": { "type": "object", "properties": { "refreshToken": { "type": "string" }, "accessToken": { "type": "string" } }, "description": "Use this to **refresh** token" }, "AuthExpireRequest_session": { "type": "object", "properties": { "authorization": { "type": "string", "description": "Authorization token generate with Access Tokens.", "example": "eyJraWQiOiJqQWNzNDFBdFBEcXdKTVN6Y0dzV01SNFR0T3hETDhcL3dtOW9qQ0JOWVdqcz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJhdWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNjEzNzUyODE3LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9PU2dRdlRhVEEiLCJjb2duaXRvOnVzZXJuYW1lIjoiamVmZiIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJlbWFpbCI6ImplZmZAdGVub3Zvcy5jb20ifQ.kzu1AddXc-HIopmmsxnnXjDiKXhOLox6P2Hx5HCg0gzupbjW9hjbMWVl0NIZRgrLJIEkYjTl9zRUre_QpiJdeVdluMVPLi6OfMUy8XskeqrOAUFDr3nqrkt99uR-LSrVd_hI8NSGvRPXEcWXV6A35Nq8_xZ8tHHlWEanGhtNcEPzgWa1JU1LdQPDCtixgwQGhroevX2TByGC_yfbimn9l5JeveQGyWKNIfvUPR9zLu2g8bPgCzCUroNWU1QRh1o-p1-8lMVwyROl3mIiCfSTo_QwtLArcFTJi5MyMsWCwWHXV" }, "accessToken": { "type": "string", "description": "Session Access Token.", "example": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.jkuKuQVDhGxbX04I3iczTCioh9ah2MA90YkOcY7DTyLS94XCvS_JpOhUSHhk70uM_ZNxLCU00OtahFm7Ktc-Zw_21qjuA40yf9Uf0KcQok5DEbv-9-_j8F4PAdChaS8Cok_-SjUoZmbiIgC-uF601vcczTHgC2SLs4FiOubdc-3tVjQrt6sf0k_W3cBBR-ajbYrDYMdHiJGEtetod88bO1WYJlSWhSddHXkjWOYE0-x3flkDswYJkEq1FKpc1lgqaeoVGShJ90H4S9Yj_FS9vHd0Yq8pwOUkCjIr_P3xFK4d9pRtEc35gkQ3QMbE1Nx93srzUx2rkI75_J2Hf3IltA.jlAjOx1FRapys-J-.YfjwTEQMsnp1wPXkKab_NvA_6lZp15ur2zNUEuX0NqC4hfQ6kbzzQXOl_nLujNwLI8YqqNgLni3l4Eu-luxHDCM2fHvjVaL6_ULJ9VThkBlkJYmxFQZX8c20EPWa1IBH630EPKslFNwPgYT113" }, "refreshToken": { "type": "string", "description": "Refresh Token generated with Access Tokens.", "example": "eyJraWQiOiJITk5BbmN6bW1NajFaMUlGNXE3SXdzM3RvbE1QWnFYRjBWVFVzUGQyTnc4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTM3NTI4MTcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX09TZ1F2VGFUQSIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJqdGkiOiI3NWJjZWYzZi03Njg3LTQ5MjgtOTY2Zi05MzM0MmQ0MjFmYjkiLCJjbGllbnRfaWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwidXNlcm5hbWUiOiJqZWZmIn0.COepDhay_VaqCHJwNOT" } }, "description": "Session information." }, "AuthExpireResponse_session": { "type": "object", "properties": { "authorization": { "type": "string", "description": "Authorization token generate with Access Tokens.", "example": "" }, "accessToken": { "type": "string", "description": "Session Access Token.", "example": "" }, "refreshToken": { "type": "string", "description": "Refresh Token generated with Access Tokens.", "example": "eyJraWQiOiJITk5BbmN6bW1NajFaMUlGNXE3SXdzM3RvbE1QWnFYRjBWVFVzUGQyTnc4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTM3NTI4MTcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX09TZ1F2VGFUQSIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJqdGkiOiI3NWJjZWYzZi03Njg3LTQ5MjgtOTY2Zi05MzM0MmQ0MjFmYjkiLCJjbGllbnRfaWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwidXNlcm5hbWUiOiJqZWZmIn0.COepDhay_VaqCHJwNOT" } }, "description": "Session information." }, "AuthResponse_session": { "type": "object", "properties": { "authorization": { "type": "string", "example": "eyJraWQiOiJqQWNzNDFBdFBEcXdKTVN6Y0dzV01SNFR0T3hETDhcL3dtOW9qQ0JOWVdqcz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJhdWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNjEzNzUyODE3LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9PU2dRdlRhVEEiLCJjb2duaXRvOnVzZXJuYW1lIjoiamVmZiIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJlbWFpbCI6ImplZmZAdGVub3Zvcy5jb20ifQ.kzu1AddXc-HIopmmsxnnXjDiKXhOLox6P2Hx5HCg0gzupbjW9hjbMWVl0NIZRgrLJIEkYjTl9zRUre_QpiJdeVdluMVPLi6OfMUy8XskeqrOAUFDr3nqrkt99uR-LSrVd_hI8NSGvRPXEcWXV6A35Nq8_xZ8tHHlWEanGhtNcEPzgWa1JU1LdQPDCtixgwQGhroevX2TByGC_yfbimn9l5JeveQGyWKNIfvUPR9zLu2g8bPgCzCUroNWU1QRh1o-p1-8lMVwyROl3mIiCfSTo_QwtLArcFTJi5MyMsWCwWHXV" }, "refreshToken": { "type": "string", "example": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.jkuKuQVDhGxbX04I3iczTCioh9ah2MA90YkOcY7DTyLS94XCvS_JpOhUSHhk70uM_ZNxLCU00OtahFm7Ktc-Zw_21qjuA40yf9Uf0KcQok5DEbv-9-_j8F4PAdChaS8Cok_-SjUoZmbiIgC-uF601vcczTHgC2SLs4FiOubdc-3tVjQrt6sf0k_W3cBBR-ajbYrDYMdHiJGEtetod88bO1WYJlSWhSddHXkjWOYE0-x3flkDswYJkEq1FKpc1lgqaeoVGShJ90H4S9Yj_FS9vHd0Yq8pwOUkCjIr_P3xFK4d9pRtEc35gkQ3QMbE1Nx93srzUx2rkI75_J2Hf3IltA.jlAjOx1FRapys-J-.YfjwTEQMsnp1wPXkKab_NvA_6lZp15ur2zNUEuX0NqC4hfQ6kbzzQXOl_nLujNwLI8YqqNgLni3l4Eu-luxHDCM2fHvjVaL6_ULJ9VThkBlkJYmxFQZX8c20EPWa1IBH630EPKslFNwPgYT113" }, "accessToken": { "type": "string", "example": "eyJraWQiOiJITk5BbmN6bW1NajFaMUlGNXE3SXdzM3RvbE1QWnFYRjBWVFVzUGQyTnc4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTM3NTI4MTcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX09TZ1F2VGFUQSIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJqdGkiOiI3NWJjZWYzZi03Njg3LTQ5MjgtOTY2Zi05MzM0MmQ0MjFmYjkiLCJjbGllbnRfaWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwidXNlcm5hbWUiOiJqZWZmIn0.COepDhay_VaqCHJwNOT" }, "expireEpoch": { "type": "number", "example": 1546300800000 } } }, "ImpersonateResponse_session": { "type": "object", "properties": { "authorization": { "type": "string", "example": "eyJraWQiOiJqQWNzNDFBdFBEcXdKTVN6Y0dzV01SNFR0T3hETDhcL3dtOW9qQ0JOWVdqcz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJhdWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNjEzNzUyODE3LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9PU2dRdlRhVEEiLCJjb2duaXRvOnVzZXJuYW1lIjoiamVmZiIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJlbWFpbCI6ImplZmZAdGVub3Zvcy5jb20ifQ.kzu1AddXc-HIopmmsxnnXjDiKXhOLox6P2Hx5HCg0gzupbjW9hjbMWVl0NIZRgrLJIEkYjTl9zRUre_QpiJdeVdluMVPLi6OfMUy8XskeqrOAUFDr3nqrkt99uR-LSrVd_hI8NSGvRPXEcWXV6A35Nq8_xZ8tHHlWEanGhtNcEPzgWa1JU1LdQPDCtixgwQGhroevX2TByGC_yfbimn9l5JeveQGyWKNIfvUPR9zLu2g8bPgCzCUroNWU1QRh1o-p1-8lMVwyROl3mIiCfSTo_QwtLArcFTJi5MyMsWCwWHXV" }, "refreshToken": { "type": "string", "example": "" }, "accessToken": { "type": "string", "example": "eyJraWQiOiJITk5BbmN6bW1NajFaMUlGNXE3SXdzM3RvbE1QWnFYRjBWVFVzUGQyTnc4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTM3NTI4MTcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX09TZ1F2VGFUQSIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJqdGkiOiI3NWJjZWYzZi03Njg3LTQ5MjgtOTY2Zi05MzM0MmQ0MjFmYjkiLCJjbGllbnRfaWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwidXNlcm5hbWUiOiJqZWZmIn0.COepDhay_VaqCHJwNOT" }, "expireEpoch": { "type": "number", "example": 1546300800000 } } }, "ControlledVocabulary_metadata": { "type": "object", "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/ControlledVocabularyValue" } }, "searchable": { "type": "boolean", "description": "Toggle searchability" } }, "description": "Vocabulary metadata" }, "ControlledVocabularyUpdateRequest_update": { "type": "object", "properties": { "valueId": { "type": "string" }, "valueName": { "type": "string" } } }, "MetadataTemplate_template": { "type": "object", "properties": { "metadataGroups": { "type": "array", "description": "List of metadata groups this template contain", "items": { "$ref": "#/components/schemas/MetadataGroup" } }, "templateId": { "type": "string", "format": "uuid" }, "templateName": { "type": "string" }, "createdEpoch": { "type": "integer", "example": 1234567890123 }, "lastUpdatedEpoch": { "type": "integer", "example": 1234567890123 }, "templateType": { "type": "array", "items": { "$ref": "#/components/schemas/MetadataTemplateType" } } } }, "CreateProofUser": { "type": "object", "properties": { "first_name": { "type": "string", "example": "Tony" }, "last_name": { "type": "string", "example": "Stark" }, "email": { "type": "string", "description": "Email address for the user", "example": "tony.stark@tenovos.com" }, "roles": { "type": "array", "description": "List of string for each account type assigned to the user", "items": { "$ref": "#/components/schemas/ProofUserRoles" } }, "phone": { "type": "string", "description": "Phone number for the user", "example": "4412345678911" }, "timezone": { "type": "string", "description": "Timezone for the user", "example": "account_owner_timezone" }, "company": { "type": "string", "description": "The company associated with the user account", "example": "Tenovos" }, "verified": { "type": "boolean", "description": "Indicates whether or not the user has confirmed their account via the email notification sent. Only available when the role is not guest. If set to true, user will not receive an email notification and will be able to login without confirming email address.", "example": false }, "password": { "type": "string", "description": "The password the user will use to login. For Tenovos federated users, this can be any password that is at least 8 characters with 1 number and 1 captial letter, and user will not use this password when accessing proofs via Tenovos federation." }, "proofing_defaults": { "type": "object", "properties": { "view": { "type": "boolean", "description": "Indicates whether the user account can view proofs", "example": true }, "comment": { "type": "boolean", "description": "Indicates whether the user account can comment on proofs", "example": true }, "decision": { "type": "boolean", "description": "Indicates whether the user account can make decisions on proofs", "example": false }, "share": { "type": "boolean", "description": "Indicates whether the user account can share proofs", "example": true }, "manage": { "type": "boolean", "description": "Indicates whether the user account can manage proofs. Should be false if user is not in the manage role", "example": false }, "notification": { "type": "string", "description": "Indicates whether the user account is configured to get notications about proofs", "example": "disabled" } } } } }, "ProofUserResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Identifier of the proofing user account created", "example": "a4fdc859-6d9e-4885-8df0-a5d315827703" }, "first_name": { "type": "string", "example": "Tony" }, "last_name": { "type": "string", "example": "Stark" }, "account_owner": { "type": "boolean", "description": "Indicated if the user is the owner of the Proofing account for the organization", "example": false }, "timezone": { "type": "string", "example": "Europe/London" }, "email": { "type": "string", "description": "Email address for the user", "example": "tony.stark@tenovos.com" }, "roles": { "type": "array", "description": "List of string for each account type assigned to the user", "items": { "$ref": "#/components/schemas/ProofUserRoles" } }, "phone": { "type": "string", "description": "Phone number for the user", "example": "4412345678911" }, "company": { "type": "string", "description": "The company associated with the user account", "example": "Tenovos" }, "verified": { "type": "boolean", "description": "Indicates whether or not the user has confirmed their account via the email notification sent", "example": "false" } } }, "RelationshipCreateRequest_secondaryIds": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the secondary asset", "format": "uuid" }, "linkType": { "type": "string", "description": "A relationship type", "enum": [ "child", "derivative", "placed-graphic" ] } } }, "RelationshipDeleteRequest_secondaryIds": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the secondary asset", "format": "uuid", "example": "f81769d1-8e93-4af7-856e-56ea30ec1038" }, "linkType": { "type": "string", "description": "Relationship type", "enum": [ "child", "placed-graphic", "derivative" ] } } }, "Search_sortBy": { "type": "object", "properties": { "metadataDefinitionSearchField": { "type": "string", "description": "Sort the result set according to specified attributes by metadata search field name", "example": "lastUpdatedEpoch" }, "order": { "type": "string", "description": "Sort Order", "example": "desc", "enum": [ "asc", "desc" ] } } }, "SearchFacetList_inner": { "type": "object", "properties": { "facet_name": { "type": "string", "description": "Name of the facet", "example": "Agency" }, "values": { "type": "array", "description": "List of facet values", "items": { "type": "object", "properties": { "key": { "type": "string", "description": "Key of the facet", "example": "Sunset Images LLC" }, "doc_count": { "type": "integer", "description": "Number of Assets against the key", "example": 3 } } } } } }, "UserCreateRequest_customAttributes": { "type": "object", "properties": { "country": { "type": "string", "description": "Country of User", "example": "USA" }, "company": { "type": "string", "description": "Company of User", "example": "Tenovos" }, "phone": { "type": "string", "description": "Phone of User", "example": "" }, "contact": { "type": "string", "description": "Contact of User", "example": "" } } }, "AdaptiveTemplateSearch": { "type": "object", "properties": { "from": { "type": "integer", "description": "The beginning index of the search. A value greater than 0 will offset the search.", "example": 0, "default": 0, "maximum": 10000, "x-nullable": false }, "limit": { "type": "integer", "default": 50, "maximum": 100, "minimum": 1, "example": 50, "description": "The maximum number of templates to return per page.", "x-nullable": true }, "searchTerm": { "type": "array", "description": "List of search terms with AND operation by default", "items": { "type": "string", "example": "*" }, "x-nullable": true }, "sortBy": { "type": "array", "description": "The metadata attribute and order to sort by.", "items": { "$ref": "#/components/schemas/Search_sortBy" }, "x-nullable": true }, "operation": { "type": "string", "description": "Indicates whether to apply an AND conditions or an OR condition between search terms", "example": "AND", "x-nullable": false } }, "required": [ "from", "limit", "sortBy", "operation" ] }, "create-asset-response": { "type": "object", "properties": { "objectId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier for the new created asset.", "example": "2dee909b-6b2b-4da8-96c3-af90fc1662ec" }, "filename": { "type": "string", "description": "Name of the file at the time of creation, or the placeholder value of a metadata-only Asset.", "example": "hooli-logo.jpg" }, "filetype": { "type": "string", "description": "MIME type of the file.", "example": "image/jpeg" }, "fileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the content/file", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "originalFileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the original content/file. Provided for versioning purposes.", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "url": { "type": "string", "format": "url", "description": "AWS S3 presigned secure URL to upload the Asset's content to. Only present for a metadata-only Asset, which has no content file yet. Files must be streamed to this URL." }, "uploadId": { "type": "string", "description": "Uniquely identifies the multipart upload session. Only present when the Asset includes content to upload; absent for a metadata-only Asset.", "example": "EXAMPLEUPLOADID" }, "urls": { "type": "array", "description": "Presigned URLs to upload the Asset's content, one per part. Only present when the Asset includes content to upload; absent for a metadata-only Asset. If the file size is greater than 100MB, multiple parts will be returned.", "items": { "type": "object", "properties": { "partNumber": { "type": "number", "description": "The part number this presigned URL corresponds to.", "example": 1 }, "url": { "type": "string", "format": "url", "description": "AWS S3 presigned secure URL to upload this content part to. Files must be streamed to this URL." } } } } } }, "renditions": { "type": "object", "properties": { "width": { "type": "integer", "example": 1920 }, "height": { "type": "integer", "example": 1080 }, "imageThumb": { "type": "string", "format": "url", "description": "Rendition of the original content with a max size of 200x200", "example": "https://env.content.tenovos.io/1588091945181/445c273a-235f-4d3b-8397-567f02f312e0/35c8cc9b-0aab-43aa-b220-7829f821836a-200x200.png" }, "imagePreview": { "type": "string", "format": "url", "description": "Rendition of the original content with a max size of 700x700", "example": "https://env.content.tenovos.io/1588091945181/445c273a-235f-4d3b-8397-567f02f312e0/35c8cc9b-0aab-43aa-b220-7829f821836a-700x700.png" }, "imagePreviewLarge": { "type": "string", "format": "url", "description": "Rendition of the original content with a max size of 1000x1000", "example": "https://env.content.tenovos.io/1588091945181/445c273a-235f-4d3b-8397-567f02f312e0/35c8cc9b-0aab-43aa-b220-7829f821836a-1000x1000.png" }, "mezzaninePreview": { "type": "string", "format": "url", "description": "Rendition of the original content with a max size of 3000x3000", "example": "https://env.content.tenovos.io/1588091945181/445c273a-235f-4d3b-8397-567f02f312e0/gilfoyle_anton-3000x3000.png" }, "imagePreviewExtraLarge": { "type": "string", "format": "url", "description": "For Tenovos customers with the Creative Editor feature, Tenovos generates an XL preview with max size of 5000x5000.", "example": "https://env.content.tenovos.io/1588091945181/445c273a-235f-4d3b-8397-567f02f312e0/35c8cc9b-0aab-43aa-b220-7829f821836a-5000x5000.png" } } }, "event-history": { "type": "object", "properties": { "total": { "type": "integer", "example": 798054, "description": "total number of results based on query parameters provided." }, "limit": { "type": "number", "description": "Reflects the value provided (or the default) for the total number of results to limit the response size per request.", "example": 100 }, "nextCursor": { "type": "string", "description": "Provides the cursor for the next page of results. If no more pages exist, this field can be null or omitted.", "example": "eyJvZmZzZXQiOjIwMH0" }, "prevCursor": { "type": "string", "description": "Provides the cursor for the previous page of results. If no previous page exists, i.e., current response is the first page, this field can be null or omitted.", "example": "kmFvYmBzZXQiOjIwNJ0" }, "events": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "object", "properties": { "eventType": { "type": "string", "description": "Combination of the Topic and the Event", "example": "asset.created" }, "id": { "type": "string", "description": "Unique identifier of the webhook event itself", "example": "some-event-type-d231cf1d-86b2-436e-95de-b745c39d2ed5" }, "time": { "type": "string", "format": "date-time", "description": "Date/Time that the webhook event occurred.", "example": "2024-05-09T17:55:28.462Z" }, "user": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The Tenovos User ID for the user who caused the event", "example": "7d675ef0-f423-11e9-8071-89c0c405214e" }, "firstName": { "type": "string", "description": "First Name of the User", "example": "Erlich" }, "lastName": { "type": "string", "description": "Last Name of the User", "example": "Bachman" } } } } } } } }, "attribute": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique attribute ID associated with this metadata field.", "example": "bcf51509-8460-4ecf-ad9d-67f09a5682f6" }, "name": { "type": "string", "description": "Metadata Attribute label/name provided by administrative user. Can be a textbox, textarea, date or dropdown.", "example": "Release Date", "minLength": 3, "maxLength": 100 }, "value": { "type": "string", "description": "The corresponding value associated to the named attribute within the response object. Required if the attribute is required for the metadata template being used.", "example": "01/01/2024", "minLength": 0, "maxLength": 2000 } } }, "table": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique attribute ID associated with this table metadata field.", "example": "b4047831-3921-4684-a434-1bb68214c111" }, "name": { "type": "string", "description": "Table label/name provided by administrative user. Tables can contain one or more rows of multiple attributes and corresponding values.", "example": "Usage Table", "minLength": 3, "maxLength": 100 }, "value": { "type": "array", "description": "Highest level array representing each row of data within the table", "items": { "type": "array", "description": "Array of objects expressing the attribute name and associated value for a given column within the table row.", "items": { "$ref": "#/components/schemas/attribute" }, "minItems": 1, "maxItems": 12 } } } }, "create-asset": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the file if creating a content based Asset.", "example": "hooli-logo.jpg" }, "objectType": { "type": "string", "description": "The type of object to create. Defaults to `Asset` if not provided.", "default": "Asset", "example": "Asset" }, "metadataTemplateId": { "type": "string", "format": "uuid", "description": "The UUID (system id) of the Metadata Template to be used.", "example": "ea6eb24d-adef-4080-bd02-f64f567c437f" }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "example": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ] ] } ] } } }, "create-asset-version": { "type": "object", "properties": { "originalFileId": { "type": "string", "description": "The Unique Identifier (system id) of the original asset this version will replace as the latest.", "example": "33df0bfb-2465-427b-ae8c-4476e7f6e112" }, "filename": { "type": "string", "description": "The name of the file if creating a content based Asset.", "example": "hooli-logo.jpg" }, "metadataTemplateId": { "type": "string", "format": "uuid", "description": "The UUID (system id) of the Metadata Template to be used.", "example": "ea6eb24d-adef-4080-bd02-f64f567c437f" }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "example": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ] ] } ] } } }, "create-multipart-asset": { "type": "object", "properties": { "filename": { "type": "string", "description": "The name of the file if creating a content based Asset.", "example": "hooli-logo.jpg" }, "metadataTemplateId": { "type": "string", "format": "uuid", "description": "The UUID (system id) of the Metadata Template to be used.", "example": "ea6eb24d-adef-4080-bd02-f64f567c437f", "required": [ "metadataTemplateId" ] }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "required": [ "securityTemplateIds" ], "example": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] }, "filesize": { "type": "number", "format": "int32", "required": [ "filesize" ], "description": "Numeric value of the filesize for the content associated to this Asset. Used to determine whether or not the file size is greater than 5GB, and will return multiple urls to upload each chunk to.", "example": 9019431322 }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ] ] } ] } } }, "create-asset-response-legacy": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status indicator returned by Tenovos", "example": "success" }, "message": { "type": "string", "description": "Message indicated whether the asset was successfully created or not.", "example": "Asset created successfully" }, "data": { "type": "object", "properties": { "objectId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier for the new created asset.", "example": "2dee909b-6b2b-4da8-96c3-af90fc1662ec" }, "filename": { "type": "string", "description": "Name of the file at the time of creation, or the placeholder value of a metadata-only Asset.", "example": "hooli-logo.jpg" }, "fileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the content/file", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "originalFileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the original content/file. Provided for versioning purposes.", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "url": { "type": "string", "format": "url", "description": "AWS S3 presigned secure URL to upload the Asset's content to. Only present for a metadata-only Asset, which has no content file yet. Files must be streamed to this URL." }, "uploadId": { "type": "string", "description": "Uniquely identifies the multipart upload session. Only present when the Asset includes content to upload; absent for a metadata-only Asset.", "example": "EXAMPLEUPLOADID" }, "urls": { "type": "array", "description": "Presigned URLs to upload the Asset's content, one per part. Only present when the Asset includes content to upload; absent for a metadata-only Asset. If the file size is greater than 100MB, multiple parts will be returned.", "items": { "type": "object", "properties": { "partNumber": { "type": "number", "description": "The part number this presigned URL corresponds to.", "example": 1 }, "url": { "type": "string", "format": "url", "description": "AWS S3 presigned secure URL to upload this content part to. Files must be streamed to this URL." } } } } } } } }, "get-asset-response": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status indicator returned by Tenovos", "example": "success" }, "message": { "type": "string", "description": "Message indicated whether the asset was successfully created or not.", "example": "Asset created successfully" }, "data": { "type": "object", "properties": { "createdDate": { "type": "string", "format": "date", "description": "System date/time of when the Asset was created", "example": "2024-06-10T12:13:23.782Z" }, "lastUpdatedDate": { "type": "string", "format": "date", "description": "System date/time that the Asset was last updated.", "example": "2024-07-12T18:42:01.102Z" }, "fileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the content/file", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "filename": { "type": "string", "description": "Name of the file at the time of creation, or the placeholder value of a metadata-only Asset.", "example": "hooli-logo.jpg" }, "fileSizeInBytes": { "type": "integer", "description": "Provides the original file size in bytes.", "example": 209743 }, "originalFileId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier of the original content/file. Provided for versioning purposes.", "example": "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1" }, "createdBy": { "type": "object", "description": "The Tenovos user who created the Asset.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique Identifier of the Tenovos user.", "example": "7d675ef0-f423-11e9-8071-89c0c4052141" }, "firstName": { "type": "string", "example": "Erlich" }, "lastName": { "type": "string", "example": "Bachman" }, "email": { "type": "string", "format": "email", "example": "erlich.bachman@piedpiper.com" } } }, "lastUpdatedBy": { "type": "object", "description": "The Tenovos user who last updated the Asset.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique Identifier of the Tenovos user.", "example": "4b5896b4-33e4-41ac-b251-39a4dbaa25b2" }, "firstName": { "type": "string", "example": "Richard" }, "lastName": { "type": "string", "example": "Hendricks" }, "email": { "type": "string", "format": "email", "example": "richard.hendricks@piedpiper.com" } } }, "assetId": { "type": "string", "format": "uuid", "description": "Tenovos generated unique identifier for the new created asset.", "example": "2dee909b-6b2b-4da8-96c3-af90fc1662ec" }, "type": { "type": "string", "description": "Indicates the type of object in the system. For example, Asset is a type of object.", "example": "Asset" }, "currentVersion": { "type": "boolean", "description": "Indicates whether or not this asset is the latest version.", "example": true }, "versionNumber": { "type": "number", "format": "int32", "example": 1718021603782 }, "AITags": { "type": "array", "items": { "type": "string", "description": "Array of strings for each Artificial Intelligence (AI) tag added to the Asset." } }, "metadataState": { "type": "string", "description": "Action metadata state", "example": "available", "enum": [ "available", "recycle bin" ] }, "metadataTemplateId": { "type": "string", "description": "Metadata Template ID", "format": "uuid", "example": "ea6eb24d-adef-4380-bd02-f64f567c437f" }, "renditionsDocument": { "type": "object", "properties": { "width": { "type": "number", "example": 435 }, "height": { "type": "number", "example": 650 }, "imageThumb": { "type": "string", "format": "url", "description": "S3 url to the thumbnail generated rendition of the Asset's content", "example": "https://url.content.tenovos.io/1588091945183/c8aaed5c-0cba-4420-87d1-506741ed5ca9/fa0bd5a4-cd0f-410b-88b0-z1m9dac003f6-200x200.png" }, "imagePreview": { "type": "string", "format": "url", "description": "S3 url to the preview generated rendition of the Asset's content", "example": "https://url.content.tenovos.io/1588091945183/c8aaed5c-0cba-4420-87d1-506741ed5ca9/fa0bd5a4-cd0f-410b-88b0-z1m9dac003f6-700x700.png" }, "mezzaninePreview": { "type": "string", "format": "url", "description": "S3 url to the mezzanine generated rendition of the Asset's content", "example": "https://url.content.tenovos.io/1588091945183/c8aaed5c-0cba-4420-87d1-506741ed5ca9/fa0bd5a4-cd0f-410b-88b0-z1m9dac003f6-3000x3000.png" }, "imagePreviewLarge": { "type": "string", "format": "url", "description": "S3 url to the large preview generated rendition of the Asset's content", "example": "https://url.content.tenovos.io/1588091945183/c8aaed5c-0cba-4420-87d1-506741ed5ca9/fa0bd5a4-cd0f-410b-88b0-z1m9dac003f6-1000x1000.png" } } }, "fileState": { "type": "string", "description": "Action content file state", "enum": [ "available", "recycle bin" ] }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "description": "Array of Unique Id's for each Security Template applied to the Asset", "example": "46ea161d-9b06-417e-88eb-f5a4244aaed5" } }, "avamTags": { "type": "array", "items": { "type": "string" } }, "lockType": { "type": "array", "items": { "type": "string" } }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "id": "a3f1b2c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c", "name": "Release Date", "value": "01/01/2024" }, { "id": "d7e8f9a0-1b2c-3d4e-5f6a-7b8c9d0e1f2a", "name": "Product", "value": "HooliDocs" }, { "id": "c4b3a2f1-6e5d-8a7f-0c9b-2e1d4a3f6b5c", "name": "Usage Table", "value": [ [ { "id": "e1f2a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b", "name": "Usage Category", "value": "E-Commerce" }, { "id": "f5a6b7c8-d9e0-1f2a-3b4c-5d6e7f8a9b0c", "name": "Usage Length", "value": "12 months" } ] ] } ] } } } } }, "update-asset": { "type": "object", "properties": { "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 50, "example": [ "b84ac1dc-30ed-4741-8f8d-47ef2635950b", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ] }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ], [ { "name": "Usage Category", "value": "Physical Retail" }, { "name": "Usage Length", "value": "18 months" } ], [ { "name": "Usage Category", "value": "Social Media" }, { "name": "Usage Length", "value": "6 months" } ] ] } ] } } }, "update-response": { "type": "object", "properties": { "status": { "type": "string", "description": "Response Status indicator returned by Tenovos", "example": "success" }, "message": { "type": "string", "description": "Message indicated whether the asset was successfully created or not.", "example": "Asset update was successful" } } }, "pull-zone": { "type": "object", "properties": { "id": { "type": "integer", "description": "The unique ID of the Pull Zone.", "example": 192011 }, "name": { "type": "string", "description": "The name of the Pull Zone", "example": "Hooli Pull Zone US" }, "enabled": { "type": "boolean", "description": "Determines if the Pull Zone is currently enabled, active and running", "example": true }, "allowedReferrers": { "type": "array", "description": "The list of referrer hostnames that are allowed to access the pull zone. Requests containing the header \"\" that is not on the list will be rejected. If empty, all referrers are allowed.", "items": { "type": "string", "description": "Url for the domain that is allowed to refer requests to the Pull Zone", "example": [ "https://company.com", "https://tenovos.io" ] } }, "blockedReferrers": { "type": "array", "description": "The list of referrer hostnames that are blocked from accessing the pull zone. The CDN will block all requests for content coming from any of the domains listed.", "items": { "type": "string", "description": "Url for the domain that is blocked from making requests to the Pull Zone", "example": [ "https://domain.com", "https://domain.io" ] } }, "blockedIPs": { "type": "array", "description": "The list of IPs that are blocked from accessing the Pull Zone. Requests coming from the following IPs will be rejected. If empty, all IPs will be allowed.", "items": { "type": "string", "description": "Url for the domain that is blocked from making requests to the Pull Zone", "example": [ "197.14.69.1", "248.167.10.12" ] } }, "enableGeoZoneUS": { "type": "boolean", "description": "Determines if delivery from the North American region is enabled for this Pull Zone.", "required": [ "enableGeoZoneUS" ], "example": true }, "enableGeoZoneEU": { "type": "boolean", "description": "Determines if delivery from the European region is enabled for this Pull zone.", "example": false }, "enableGeoZoneAsia": { "type": "boolean", "description": "Determines if delivery from the Asia region is enabled for this Pull zone.", "example": true }, "enableGeoZoneSA": { "type": "boolean", "description": "Determines if delivery from the South American region is enabled for this Pull zone.", "example": true }, "enableGeoZoneAF": { "type": "boolean", "description": "Determines if delivery from the Africa region is enabled for this Pull zone.", "example": true }, "zoneSecurityEnabled": { "type": "boolean", "description": "True if the URL secure token authentication security is enabled", "example": false }, "zoneSecurityKey": { "type": "string", "description": "The security key used for secure URL token authentication.", "example": "d9f8c7a6e5b4a3f2d1c0b9a8e7f6d5c4" }, "monthlyBandwidthLimit": { "type": "integer", "description": "The monthly limit of bandwidth in bytes that the pullzone is allowed to use.", "required": [ "monthlyBandwidthLimit" ], "example": 10737418240 }, "monthlyBandwidthUsed": { "type": "integer", "description": "The amount of bandwidth in bytes that the Pull Zone has used this month.", "required": [ "monthlyBandwidthLimit" ], "example": 7737418240 }, "enableAccessControlOriginHeader": { "type": "boolean", "description": "Determines if the CORS headers should be enabled", "example": true }, "accessControlOriginHeaderExtensions": { "type": "array", "description": "Array of file extensions (strings) that specifies which file types should include CORS headers (like Access-Control-Allow-Origin) in the CDN response.", "items": { "type": "string", "description": "A file extension, with the leading dot (e.g., .json, not json). When a file request matches one of these extensions, Tenovos CDN will add CORS headers to the response. This is important for files like fonts, json, and images or videos used in webpages. Only list the types of files that you intend to acccess cross-origin.", "example": ".png" }, "example": [ ".jpg", ".jpeg", ".png", ".webp", ".avif", ".mp4", ".woff2" ] }, "blockedCountries": { "type": "array", "description": "The list of blocked countries listed using their two-letter Alpha2 ISO codes", "items": { "type": "string", "example": "PK" }, "example": [ "PK", "CN", "BY", "IR", "KP", "RU", "SY", "VE", "YE", "AF", "MM", "SD" ] }, "cnameDomain": { "type": "string", "description": "The CNAME domain of the pull zone for setting up custom hostnames", "example": "https://cdn.cusotmerdomain.net" }, "enableOptimization": { "type": "boolean", "required": [ "enableOptimization" ], "description": "If true, the CDN will optimize content such as images, css, and javascript in order to serve lighter, faster assets tailored to the requesting device/browser. When true, Tenovos will automatically convert supported image formats to webP on the fly and cache it seperatly to servce to clients that support webP format.", "example": true } } }, "cdn-pullzone-stats": { "type": "object", "properties": { "totalBandwidthUsed": { "type": "integer", "description": "The total bandwidth used in the given time range", "example": 7562312 }, "totalOriginTraffic": { "type": "integer", "description": "The total bandwidth used fetching content from Tenovos", "example": 1236652 }, "totalRequestsServed": { "type": "integer", "description": "The total number of requests served by the CDN in the given time range", "example": 1564892 }, "cacheHitRate": { "type": "number", "format": "double", "description": "The percentage of requests served directly from the CDN cache instead of the origin" } } }, "metadata-attributes": { "type": "array", "minItems": 0, "maxItems": 2500, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute (same as metadataDefinitionId)", "example": "8a481dd2-24c1-4c54-a84f-0aded1e985e7" }, "name": { "type": "string", "description": "The name given to the Metadata Attribute", "example": "Program Name" }, "searchField": { "type": "string", "description": "The value assigned by Tenovos and used for search indexes. This value never changes, even if attribute name changes. Use this value to perform attribute specific searches, or to uniquely identify attributes in Requests, etc.", "example": "program_name" }, "type": { "type": "string", "description": "Identifies the type of Metadata Attribute used", "example": "text", "enum": [ "text", "textarea", "date", "dropdown" ] } } } }, "metadata-attribute-list": { "type": "object", "description": "Paginated list of metadata attributes.", "properties": { "hitCount": { "type": "integer", "description": "Total number of attributes matching the search criteria.", "example": 84 }, "results": { "type": "array", "description": "Array of attribute summary objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "8a481dd2-24c1-4c54-a84f-0aded1e985e7" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Title" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing.", "example": "asset_title" }, "attributeType": { "type": "string", "description": "Type of the attribute.", "enum": [ "textbox", "textarea", "date", "dropdown" ], "example": "textbox" }, "isFeatured": { "type": "boolean", "description": "Whether this is a featured attribute.", "example": false }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "usedIn": { "type": "object", "description": "Describes where the attribute is currently referenced.", "properties": { "metadataCascades": { "type": "array", "description": "Cascades that reference this attribute. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1d2e3f4-1234-5678-abcd-ef1234567890" }, "name": { "type": "string", "example": "General Cascade" } } } }, "metadataTables": { "type": "array", "description": "Tables that reference this attribute. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1d2e3f4-1234-5678-abcd-ef1234567890" }, "name": { "type": "string", "example": "General Table" } } } }, "metadataGroups": { "type": "array", "description": "Groups that contain this attribute. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c1d2e3f4-1234-5678-abcd-ef1234567890" }, "name": { "type": "string", "example": "General Information" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that reference this attribute. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "example": "Product Content" } } } }, "presets": { "type": "array", "description": "Filter presets that reference this attribute. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "example": "Default Preset" } } } } } } } } } } }, "create-metadata-attribute-textbox": { "type": "object", "description": "Request body for creating a textbox metadata attribute.", "required": [ "attributeType", "name" ], "properties": { "attributeType": { "type": "string", "description": "Must be `textbox`.", "enum": [ "textbox" ], "example": "textbox" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Title" }, "tooltipText": { "type": "string", "description": "Tooltip helper text displayed to users. Maximum 100 characters.", "maxLength": 100, "example": "Enter the title of the asset" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. A required attribute cannot also be sensitive, and cannot have technical metadata mappings.", "default": false, "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search.", "default": false, "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires `isSearchable` to be true.", "default": false, "example": false }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "default": false, "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if `isRequired` is true.", "default": false, "example": false }, "isTypeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled. A typeahead attribute cannot have technical metadata mappings.", "default": false, "example": true }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Maximum value is 250 for textbox.", "maximum": 250, "example": 250 }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required or typeahead.", "items": { "type": "string" }, "example": [ "assetTitle", "fileName" ] } } }, "create-metadata-attribute-textarea": { "type": "object", "description": "Request body for creating a textarea metadata attribute.", "required": [ "attributeType", "name" ], "properties": { "attributeType": { "type": "string", "description": "Must be `textarea`.", "enum": [ "textarea" ], "example": "textarea" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Description" }, "tooltipText": { "type": "string", "description": "Tooltip helper text displayed to users. Maximum 100 characters.", "maxLength": 100, "example": "Enter the Description of the asset" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. A required attribute cannot also be sensitive, and cannot have technical metadata mappings.", "default": false, "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search.", "default": false, "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "default": false, "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if `isRequired` is true.", "default": false, "example": false }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Maximum value is 10000 for textarea.", "maximum": 10000, "example": 10000 }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required.", "items": { "type": "string" }, "example": [ "fileName", "fileType" ] } } }, "create-metadata-attribute-date": { "type": "object", "description": "Request body for creating a date metadata attribute.", "required": [ "attributeType", "name" ], "properties": { "attributeType": { "type": "string", "description": "Must be `date`.", "enum": [ "date" ], "example": "date" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Publication Date" }, "tooltipText": { "type": "string", "description": "Tooltip helper text displayed to users. Maximum 100 characters.", "maxLength": 100, "example": "The date this asset was published" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. A required attribute cannot also be sensitive.", "default": false, "example": false }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search.", "default": false, "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires `isSearchable` to be true.", "default": false, "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "default": false, "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if `isRequired` is true.", "default": false, "example": false } } }, "create-metadata-attribute-dropdown": { "type": "object", "description": "Request body for creating a dropdown metadata attribute.", "required": [ "attributeType", "name", "vocabularyId" ], "properties": { "attributeType": { "type": "string", "description": "Must be `dropdown`.", "enum": [ "dropdown" ], "example": "dropdown" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Category" }, "tooltipText": { "type": "string", "description": "Tooltip helper text displayed to users. Maximum 100 characters.", "maxLength": 100, "example": "Select the category for this asset" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. A required attribute cannot also be sensitive.", "default": false, "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search.", "default": false, "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires `isSearchable` to be true.", "default": false, "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "default": false, "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if `isRequired` is true.", "default": false, "example": false }, "vocabularyId": { "type": "string", "format": "uuid", "description": "UUID of the controlled vocabulary to associate. Required for dropdown type. Cannot be changed after creation.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "multiSelect": { "type": "boolean", "description": "Whether multi-select is enabled.", "default": false, "example": false }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required.", "items": { "type": "string" }, "example": [ "fileName" ] }, "synonyms": { "type": "array", "description": "Synonyms for vocabulary values.", "items": { "type": "object", "required": [ "valueId", "keywords" ], "properties": { "valueId": { "type": "string", "format": "uuid", "description": "UUID of the vocabulary value.", "example": "8cd2c221-6a91-4dc6-9379-d55dca9d5313" }, "keywords": { "type": "array", "description": "Synonym keywords for this vocabulary value.", "items": { "type": "string" }, "example": [ "Test Synonym", "123 synonym" ] } } } } } }, "metadata-attribute-textbox": { "type": "object", "description": "Response for a textbox metadata attribute.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Title" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing. Immutable after creation.", "example": "asset_title" }, "attributeType": { "type": "string", "description": "Always `textbox` for this schema.", "enum": [ "textbox" ], "example": "textbox" }, "customerId": { "type": "string", "description": "ID of the customer/tenant.", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "UUID of the user who created the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "UUID of the user who last updated the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "isRequired": { "type": "boolean", "example": true }, "isSearchable": { "type": "boolean", "example": true }, "isFacetable": { "type": "boolean", "example": false }, "isReadOnly": { "type": "boolean", "example": false }, "isSensitive": { "type": "boolean", "example": false }, "isSystem": { "type": "boolean", "description": "System-controlled.", "example": false }, "isVisible": { "type": "boolean", "description": "System-controlled.", "example": true }, "isRestricted": { "type": "boolean", "description": "System-controlled.", "example": false }, "isFeatured": { "type": "boolean", "description": "System-controlled.", "example": false }, "isSortByHitCount": { "type": "boolean", "description": "System-controlled.", "example": false }, "tooltipText": { "type": "string", "example": "Enter the title of the asset" }, "technicalMetadataMapping": { "type": "array", "items": { "type": "string" }, "example": [ "fileName", "fileType" ] }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Max 250 for textbox.", "example": 250 }, "isTypeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled.", "example": true }, "usedIn": { "type": "object", "description": "Describes where the attribute is currently referenced. Present on GET by ID responses.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "metadata-attribute-textarea": { "type": "object", "description": "Response for a textarea metadata attribute.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "63df1346-13dd-57g7-9cec-16349d87cg94" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Description" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing. Immutable after creation.", "example": "asset_description" }, "attributeType": { "type": "string", "description": "Always `textarea` for this schema.", "enum": [ "textarea" ], "example": "textarea" }, "customerId": { "type": "string", "description": "ID of the customer/tenant.", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "UUID of the user who created the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "UUID of the user who last updated the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "isRequired": { "type": "boolean", "example": true }, "isSearchable": { "type": "boolean", "example": true }, "isFacetable": { "type": "boolean", "description": "Always false for textarea. Textarea attributes cannot be facetable.", "example": false }, "isReadOnly": { "type": "boolean", "example": false }, "isSensitive": { "type": "boolean", "example": false }, "isSystem": { "type": "boolean", "description": "System-controlled.", "example": false }, "isVisible": { "type": "boolean", "description": "System-controlled.", "example": true }, "isRestricted": { "type": "boolean", "description": "System-controlled.", "example": false }, "isFeatured": { "type": "boolean", "description": "System-controlled.", "example": false }, "isSortByHitCount": { "type": "boolean", "description": "System-controlled.", "example": false }, "tooltipText": { "type": "string", "example": "Enter the Description of the asset" }, "technicalMetadataMapping": { "type": "array", "items": { "type": "string" }, "example": [ "fileName", "fileType" ] }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Max 10000 for textarea.", "example": 10000 }, "isTypeahead": { "type": "boolean", "description": "Always false for textarea. Textarea attributes cannot support typeahead.", "example": false }, "usedIn": { "type": "object", "description": "Describes where the attribute is currently referenced. Present on GET by ID responses.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "metadata-attribute-date": { "type": "object", "description": "Response for a date metadata attribute.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "77ab1234-11bb-22cc-33dd-44ee55ff6677" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Publication Date" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing. Immutable after creation.", "example": "publication_date" }, "attributeType": { "type": "string", "description": "Always `date` for this schema.", "enum": [ "date" ], "example": "date" }, "customerId": { "type": "string", "description": "ID of the customer/tenant.", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "UUID of the user who created the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "UUID of the user who last updated the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "isRequired": { "type": "boolean", "example": false }, "isSearchable": { "type": "boolean", "example": true }, "isFacetable": { "type": "boolean", "example": true }, "isReadOnly": { "type": "boolean", "example": false }, "isSensitive": { "type": "boolean", "example": false }, "isSystem": { "type": "boolean", "description": "System-controlled.", "example": false }, "isVisible": { "type": "boolean", "description": "System-controlled.", "example": true }, "isRestricted": { "type": "boolean", "description": "System-controlled.", "example": false }, "isFeatured": { "type": "boolean", "description": "System-controlled.", "example": false }, "isSortByHitCount": { "type": "boolean", "description": "System-controlled.", "example": false }, "tooltipText": { "type": "string", "example": "The date this asset was published" }, "technicalMetadataMapping": { "type": "array", "description": "Empty array for date attributes.", "items": { "type": "string" }, "example": [] }, "usedIn": { "type": "object", "description": "Describes where the attribute is currently referenced. Present on GET by ID responses.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "metadata-attribute-dropdown": { "type": "object", "description": "Response for a dropdown metadata attribute.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "99ff8765-aa11-bb22-cc33-dd44ee55ff66" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Asset Category" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing. Immutable after creation.", "example": "asset_category" }, "attributeType": { "type": "string", "description": "Always `dropdown` for this schema.", "enum": [ "dropdown" ], "example": "dropdown" }, "customerId": { "type": "string", "description": "ID of the customer/tenant.", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "UUID of the user who created the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "UUID of the user who last updated the attribute.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-11T14:32:35Z" }, "isRequired": { "type": "boolean", "example": true }, "isSearchable": { "type": "boolean", "example": true }, "isFacetable": { "type": "boolean", "example": true }, "isReadOnly": { "type": "boolean", "example": false }, "isSensitive": { "type": "boolean", "example": false }, "isSystem": { "type": "boolean", "description": "System-controlled.", "example": false }, "isVisible": { "type": "boolean", "description": "System-controlled.", "example": true }, "isRestricted": { "type": "boolean", "description": "System-controlled.", "example": false }, "isFeatured": { "type": "boolean", "description": "System-controlled.", "example": false }, "isSortByHitCount": { "type": "boolean", "description": "System-controlled.", "example": false }, "tooltipText": { "type": "string", "example": "Select the category for this asset" }, "technicalMetadataMapping": { "type": "array", "items": { "type": "string" }, "example": [ "fileName" ] }, "vocabularyId": { "type": "string", "format": "uuid", "description": "UUID of the associated controlled vocabulary.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "isMultiSelect": { "type": "boolean", "description": "Whether multi-select is enabled.", "example": false }, "synonyms": { "type": "array", "description": "Synonyms associated with vocabulary values.", "items": { "type": "object", "properties": { "valueId": { "type": "string", "format": "uuid", "example": "8cd2c221-6a91-4dc6-9379-d55dca9d5313" }, "keywords": { "type": "array", "items": { "type": "string" }, "example": [ "Test Synonym", "123 synonym" ] } } } }, "usedIn": { "type": "object", "description": "Describes where the attribute is currently referenced. Present on GET by ID responses.", "properties": { "metadataGroups": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "metadataTemplates": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } }, "presets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" } } } } } } } }, "update-metadata-attribute-textbox": { "type": "object", "description": "Partial update request for a textbox attribute. Only fields provided will be updated.", "properties": { "name": { "type": "string", "description": "Display name of the attribute.", "example": "Updated Asset Title" }, "tooltipText": { "type": "string", "description": "Tooltip helper text. Maximum 100 characters.", "maxLength": 100, "example": "Updated tooltip text" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. Cannot be true if isSensitive is true.", "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search. Must be true if isFacetable is true.", "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires isSearchable to be true.", "example": false }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if isRequired is true.", "example": false }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Cannot exceed 250 for textbox.", "maximum": 250, "example": 100 }, "isTypeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled. A typeahead attribute cannot have technicalMetadataMapping.", "example": false }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required or typeahead.", "items": { "type": "string" }, "example": [ "fileName" ] } } }, "update-metadata-attribute-textarea": { "type": "object", "description": "Partial update request for a textarea attribute. Only fields provided will be updated.", "properties": { "name": { "type": "string", "description": "Display name of the attribute.", "example": "Updated Description Field" }, "tooltipText": { "type": "string", "description": "Tooltip helper text. Maximum 100 characters.", "maxLength": 100, "example": "Updated tooltip text" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. Cannot be true if isSensitive is true.", "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search.", "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if isRequired is true.", "example": false }, "maxCharacterLength": { "type": "integer", "description": "Maximum allowed character length. Cannot exceed 10000 for textarea.", "maximum": 10000, "example": 5000 }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required.", "items": { "type": "string" }, "example": [ "fileName" ] } } }, "update-metadata-attribute-date": { "type": "object", "description": "Partial update request for a date attribute. Only fields provided will be updated.", "properties": { "name": { "type": "string", "description": "Display name of the attribute.", "example": "Updated Publication Date" }, "tooltipText": { "type": "string", "description": "Tooltip helper text. Maximum 100 characters.", "maxLength": 100, "example": "Updated tooltip text" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. Cannot be true if isSensitive is true.", "example": false }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search. Must be true if isFacetable is true.", "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires isSearchable to be true.", "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if isRequired is true.", "example": false } } }, "update-metadata-attribute-dropdown": { "type": "object", "description": "Partial update request for a dropdown attribute. Only fields provided will be updated.", "properties": { "name": { "type": "string", "description": "Display name of the attribute.", "example": "Updated Asset Category" }, "tooltipText": { "type": "string", "description": "Tooltip helper text. Maximum 100 characters.", "maxLength": 100, "example": "Updated tooltip text" }, "isRequired": { "type": "boolean", "description": "Whether this attribute is required. Cannot be true if isSensitive is true.", "example": true }, "isSearchable": { "type": "boolean", "description": "Whether this attribute is indexed for search. Must be true if isFacetable is true.", "example": true }, "isFacetable": { "type": "boolean", "description": "Whether this attribute can be used as a search facet/filter. Requires isSearchable to be true.", "example": true }, "isReadOnly": { "type": "boolean", "description": "Whether this attribute is read-only.", "example": false }, "isSensitive": { "type": "boolean", "description": "Whether this attribute contains sensitive data. Cannot be true if isRequired is true.", "example": false }, "isMultiSelect": { "type": "boolean", "description": "Whether multi-select is enabled. Can be changed from false to true, but NOT from true to false.", "example": true }, "technicalMetadataMapping": { "type": "array", "description": "System field references mapped to this attribute. Cannot be set if attribute is required.", "items": { "type": "string" }, "example": [ "category" ] }, "synonyms": { "type": "array", "description": "Synonyms for vocabulary values.", "items": { "type": "object", "required": [ "valueId", "keywords" ], "properties": { "valueId": { "type": "string", "format": "uuid", "description": "UUID of the vocabulary value.", "example": "8cd2c221-6a91-4dc6-9379-d55dca9d5313" }, "keywords": { "type": "array", "description": "Synonym keywords for this vocabulary value.", "items": { "type": "string" }, "example": [ "Updated Synonym", "New keyword" ] } } } } } }, "metadata-group-list": { "type": "object", "description": "Paginated list of metadata groups.", "properties": { "hitCount": { "type": "integer", "description": "Total number of groups matching the search criteria.", "example": 12 }, "results": { "type": "array", "description": "Array of group summary objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the group.", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" }, "name": { "type": "string", "description": "Display name of the group.", "example": "Product Information" }, "searchField": { "type": "string", "description": "System-generated slug.", "example": "product_information" }, "isGroupNameVisible": { "type": "boolean", "description": "Whether the group name is visible when rendered on an asset.", "example": false }, "inUse": { "type": "boolean", "description": "Derived from `usedIn` — `true` when `usedIn.metadataTemplates` is non-empty.", "example": true }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-20T12:05:27Z" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-20T12:05:27Z" }, "usedIn": { "type": "object", "description": "Describes where the group is currently referenced.", "properties": { "metadataTemplates": { "type": "array", "description": "Templates that reference this group. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "example": "Product Content" } } } } } } } } } } }, "create-metadata-group": { "type": "object", "required": [ "name", "attributeIds" ], "properties": { "name": { "type": "string", "description": "Display name of the metadata group.", "example": "Product Information" }, "attributeIds": { "type": "array", "description": "Ordered list of attribute IDs to include in the group. Order is preserved in the response.", "items": { "type": "string", "format": "uuid" }, "example": [ "01dc8715-c660-44cb-b3a4-70f4779e6651", "b1feb2cd-ab35-4fc6-917a-37a2e8419167", "187f9ef9-b1e7-4a33-95e3-8ee99206d9fc", "013ad220-b377-432d-bc6d-b1614dbb82c1" ] }, "isGroupNameVisible": { "type": "boolean", "description": "Whether the group name is visible when rendered on an asset. Defaults to false.", "default": false, "example": false } } }, "metadata-group": { "type": "object", "description": "A single metadata group object with resolved attributes.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the group.", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" }, "name": { "type": "string", "description": "Display name of the group.", "example": "Product Information" }, "searchField": { "type": "string", "description": "System-generated slug derived from the group name. Immutable after creation.", "example": "product_information" }, "customerId": { "type": "string", "description": "ID of the customer/tenant.", "example": "1739271540099" }, "createdBy": { "type": "string", "format": "uuid", "description": "UUID of the user who created the group.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "Human-readable creation date in ISO 8601 format.", "example": "2026-03-20T12:05:27Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "UUID of the user who last updated the group.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "Human-readable last updated date in ISO 8601 format.", "example": "2026-03-20T12:05:27Z" }, "isGroupNameVisible": { "type": "boolean", "description": "Whether the group name is visible when rendered on an asset.", "example": false }, "usedIn": { "type": "object", "description": "Describes where the group is currently referenced. Present on GET by ID responses.", "properties": { "metadataTemplates": { "type": "array", "description": "Templates that reference this group. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "name": { "type": "string", "example": "Product Content" } } } } } }, "attributes": { "type": "array", "description": "Ordered list of attributes in the group.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "ID of the attribute.", "example": "01dc8715-c660-44cb-b3a4-70f4779e6651" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Product Name" }, "attributeType": { "type": "string", "description": "Type of the attribute.", "example": "textbox" } } } } } }, "update-metadata-group": { "type": "object", "description": "Partial update request. Only fields provided will be updated. Omitted fields remain unchanged.", "properties": { "name": { "type": "string", "description": "Updated display name of the group.", "example": "Updated Group Name" }, "attributeIds": { "type": "array", "description": "Updated ordered list of attribute IDs. Replaces the existing list entirely. Order is preserved.", "items": { "type": "string", "format": "uuid" }, "example": [ "01dc8715-c660-44cb-b3a4-70f4779e6651", "013ad220-b377-432d-bc6d-b1614dbb82c1" ] }, "isGroupNameVisible": { "type": "boolean", "description": "Whether the group name is visible when rendered on an asset.", "example": true } } }, "template-attribute-text": { "type": "object", "description": "A text attribute within a metadata template group. Identified by `type: text`. \nThe `subType` field distinguishes between textbox and textarea variants:\n- **textBox** — short text, max 250 characters, supports typeahead\n- **textArea** — long text, max 10000 characters, cannot be facetable or typeahead", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "01dc8715-c660-44cb-b3a4-70f4779e6651" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Product Name" }, "type": { "type": "string", "description": "Always `text` for this schema.", "enum": [ "text" ], "example": "text" }, "subType": { "type": "string", "description": "Distinguishes between text variants:\n- `textBox` — short text field (max 250 chars), supports typeahead and faceting\n- `textArea` — long text field (max 10000 chars), cannot be facetable or typeahead", "enum": [ "textBox", "textArea" ], "example": "textBox" }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "product_name" }, "attributeOrder": { "type": "integer", "description": "Display order within the group.", "example": 1 }, "length": { "type": "integer", "description": "Maximum character length. Max 250 for textBox, max 10000 for textArea.", "example": 100 }, "tooltip": { "type": "string", "description": "Tooltip helper text.", "example": "" }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "required": { "type": "boolean", "description": "Whether the attribute is required.", "example": false }, "readonly": { "type": "boolean", "description": "Whether the attribute is read-only.", "example": false }, "facetable": { "type": "boolean", "description": "Whether the attribute can be used as a search facet. Always false for textArea.", "example": true }, "sensitive": { "type": "boolean", "description": "Whether the attribute contains sensitive data.", "example": false }, "typeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled. Always false for textArea.", "example": false }, "featured": { "type": "boolean", "description": "Whether the attribute is featured.", "example": false }, "isRestricted": { "type": "boolean", "description": "Whether the attribute is restricted.", "example": false }, "isMultipleSelect": { "type": "boolean", "description": "Whether multi-select is enabled. Always false for text.", "example": false }, "sortByHitCount": { "type": "boolean", "description": "Whether results are sorted by hit count.", "example": false }, "dateFormat": { "type": "string", "description": "Always \"N/A\" for text attributes.", "example": "N/A" }, "techMetaMapping": { "type": "string", "description": "Technical metadata mapping configuration. Empty string if none.", "example": "" } }, "required": [ "id", "name", "type", "subType", "searchField" ] }, "template-attribute-controlled-vocabulary": { "type": "object", "description": "A controlled vocabulary (dropdown) attribute within a metadata template group. Identified by type: controlledVocabulary.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "edb9d604-4598-4a44-bd1a-07663d3ad98c" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Usage Mediums" }, "type": { "type": "string", "description": "Always `controlledVocabulary` for this schema.", "enum": [ "controlledVocabulary" ], "example": "controlledVocabulary" }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "usage_mediums" }, "attributeOrder": { "type": "integer", "description": "Display order within the group.", "example": 2 }, "tooltip": { "type": "string", "description": "Tooltip helper text.", "example": "" }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "required": { "type": "boolean", "description": "Whether the attribute is required.", "example": false }, "readonly": { "type": "boolean", "description": "Whether the attribute is read-only.", "example": false }, "facetable": { "type": "boolean", "description": "Whether the attribute can be used as a search facet.", "example": true }, "sensitive": { "type": "boolean", "description": "Whether the attribute contains sensitive data.", "example": false }, "typeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled.", "example": false }, "featured": { "type": "boolean", "description": "Whether the attribute is featured.", "example": false }, "isRestricted": { "type": "boolean", "description": "Whether the attribute is restricted.", "example": false }, "isMultipleSelect": { "type": "boolean", "description": "Whether multi-select is enabled.", "example": true }, "sortByHitCount": { "type": "boolean", "description": "Whether results are sorted by hit count.", "example": false }, "dateFormat": { "type": "string", "description": "Always \"N/A\" for controlled vocabulary attributes.", "example": "N/A" }, "techMetaMapping": { "type": "string", "description": "Technical metadata mapping configuration. Empty string if none.", "example": "" }, "controlledVocabularyId": { "type": "string", "format": "uuid", "description": "ID of the associated controlled vocabulary.", "example": "34abed31-4546-4f15-ae07-3d22b9b056d5" } }, "required": [ "id", "name", "type", "searchField", "controlledVocabularyId" ] }, "template-attribute-date": { "type": "object", "description": "A date attribute within a metadata template group. Identified by type: date.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "8f8b3394-66db-4984-9b79-39cc721006e9" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Event Date" }, "type": { "type": "string", "description": "Always `date` for this schema.", "enum": [ "date" ], "example": "date" }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "event_date" }, "attributeOrder": { "type": "integer", "description": "Display order within the group.", "example": 4 }, "tooltip": { "type": "string", "description": "Tooltip helper text.", "example": "" }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "required": { "type": "boolean", "description": "Whether the attribute is required.", "example": false }, "readonly": { "type": "boolean", "description": "Whether the attribute is read-only.", "example": false }, "facetable": { "type": "boolean", "description": "Whether the attribute can be used as a search facet.", "example": false }, "sensitive": { "type": "boolean", "description": "Whether the attribute contains sensitive data.", "example": false }, "typeahead": { "type": "boolean", "description": "Whether typeahead/autocomplete is enabled. Always false for date.", "example": false }, "featured": { "type": "boolean", "description": "Whether the attribute is featured.", "example": true }, "isRestricted": { "type": "boolean", "description": "Whether the attribute is restricted.", "example": false }, "isMultipleSelect": { "type": "boolean", "description": "Whether multi-select is enabled. Always false for date.", "example": false }, "sortByHitCount": { "type": "boolean", "description": "Whether results are sorted by hit count.", "example": false }, "dateFormat": { "type": "string", "description": "Date format pattern used for display.", "example": "MM/dd/yyyy" }, "techMetaMapping": { "type": "string", "description": "Technical metadata mapping configuration. Empty string if none.", "example": "" } }, "required": [ "id", "name", "type", "searchField", "dateFormat" ] }, "template-attribute-table-field-textbox": { "type": "object", "description": "A textbox field within a table attribute. Identified by type: text and subType: textBox.", "properties": { "id": { "type": "string", "format": "uuid", "example": "721b8cf5-91af-4715-aedb-8d15713ee908" }, "name": { "type": "string", "example": "Event Name" }, "type": { "type": "string", "enum": [ "text" ], "example": "text" }, "subType": { "type": "string", "enum": [ "textBox" ], "example": "textBox" }, "searchField": { "type": "string", "example": "event_name" }, "fieldOrder": { "type": "integer", "description": "Display order within the table.", "example": 2 }, "length": { "type": "integer", "description": "Maximum character length.", "example": 120 }, "tooltip": { "type": "string", "example": "" }, "visible": { "type": "boolean", "example": true }, "required": { "type": "boolean", "example": true }, "readonly": { "type": "boolean", "example": false }, "facetable": { "type": "boolean", "example": false }, "sensitive": { "type": "boolean", "example": false }, "typeahead": { "type": "boolean", "example": false }, "featured": { "type": "boolean", "example": true }, "isRestricted": { "type": "boolean", "example": false }, "isMultipleSelect": { "type": "boolean", "example": false }, "sortByHitCount": { "type": "boolean", "example": false }, "dateFormat": { "type": "string", "example": "N/A" }, "techMetaMapping": { "type": "string", "example": "" } }, "required": [ "id", "name", "type", "subType", "searchField", "fieldOrder" ] }, "template-attribute-table-field-controlled-vocabulary": { "type": "object", "description": "A controlled vocabulary field within a table attribute. Identified by type: controlledVocabulary.", "properties": { "id": { "type": "string", "format": "uuid", "example": "013ad220-b377-432d-bc6d-b1614dbb82c1" }, "name": { "type": "string", "example": "Event Type" }, "type": { "type": "string", "enum": [ "controlledVocabulary" ], "example": "controlledVocabulary" }, "searchField": { "type": "string", "example": "event_type" }, "fieldOrder": { "type": "integer", "description": "Display order within the table.", "example": 1 }, "visible": { "type": "boolean", "example": true }, "required": { "type": "boolean", "example": false }, "readonly": { "type": "boolean", "example": false }, "facetable": { "type": "boolean", "example": true }, "typeahead": { "type": "boolean", "example": false }, "featured": { "type": "boolean", "example": true }, "isRestricted": { "type": "boolean", "example": false }, "isMultipleSelect": { "type": "boolean", "example": false }, "sortByHitCount": { "type": "boolean", "example": false }, "dateFormat": { "type": "string", "example": "N/A" }, "techMetaMapping": { "type": "string", "example": "" }, "controlledVocabularyId": { "type": "string", "format": "uuid", "description": "ID of the associated controlled vocabulary.", "example": "880d52d8-3372-41f7-a715-dbdd729a29b7" } }, "required": [ "id", "name", "type", "searchField", "fieldOrder", "controlledVocabularyId" ] }, "template-attribute-table-field-date": { "type": "object", "description": "A date field within a table attribute. Identified by type: date.", "properties": { "id": { "type": "string", "format": "uuid", "example": "8f8b3394-66db-4984-9b79-39cc721006e9" }, "name": { "type": "string", "example": "Event Date" }, "type": { "type": "string", "enum": [ "date" ], "example": "date" }, "searchField": { "type": "string", "example": "event_date" }, "fieldOrder": { "type": "integer", "description": "Display order within the table.", "example": 4 }, "visible": { "type": "boolean", "example": true }, "required": { "type": "boolean", "example": false }, "readonly": { "type": "boolean", "example": false }, "facetable": { "type": "boolean", "example": false }, "typeahead": { "type": "boolean", "example": false }, "featured": { "type": "boolean", "example": true }, "isRestricted": { "type": "boolean", "example": false }, "isMultipleSelect": { "type": "boolean", "example": false }, "sortByHitCount": { "type": "boolean", "example": false }, "dateFormat": { "type": "string", "description": "Date format pattern used for display.", "example": "MM/dd/yyyy" }, "techMetaMapping": { "type": "string", "example": "" } }, "required": [ "id", "name", "type", "searchField", "fieldOrder", "dateFormat" ] }, "template-attribute-table-field-cascade": { "type": "object", "description": "A cascade attribute field within a table attribute. Identified by type: cascadeAttribute.", "properties": { "id": { "type": "string", "format": "uuid", "example": "5ec692fc-e03b-43f9-a3e4-966565bd6812" }, "name": { "type": "string", "example": "Country Region Cascade" }, "type": { "type": "string", "enum": [ "cascadeAttribute" ], "example": "cascadeAttribute" }, "searchField": { "type": "string", "example": "country_region_cascade" }, "fieldOrder": { "type": "integer", "description": "Display order within the table.", "example": 1 }, "visible": { "type": "boolean", "example": true }, "dateFormat": { "type": "string", "example": "N/A" }, "cascadeMapId": { "type": "string", "format": "uuid", "description": "ID of the cascade map defining the hierarchy.", "example": "cba796a5-7a5a-4efc-b3d8-03bfee5663f1" }, "cascadeNameVisible": { "type": "boolean", "description": "Whether the cascade name is displayed.", "example": true }, "cascadeFieldsDenormalized": { "type": "array", "description": "Ordered list of cascade levels.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "type": { "type": "string", "enum": [ "controlledVocabulary" ] }, "subType": { "type": "string", "enum": [ "textBox" ] }, "searchField": { "type": "string" }, "cascadeOrder": { "type": "integer", "description": "Zero-based depth in the cascade hierarchy." }, "visible": { "type": "boolean" }, "required": { "type": "boolean" }, "readonly": { "type": "boolean" }, "facetable": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "typeahead": { "type": "boolean" }, "featured": { "type": "boolean" }, "isRestricted": { "type": "boolean" }, "isMultipleSelect": { "type": "boolean" }, "sortByHitCount": { "type": "boolean" }, "dateFormat": { "type": "string" }, "tooltip": { "type": "string" }, "techMetaMapping": { "type": "string" }, "controlledVocabularyId": { "type": "string", "format": "uuid" } } } } }, "required": [ "id", "name", "type", "searchField", "fieldOrder", "cascadeMapId", "cascadeFieldsDenormalized" ] }, "template-attribute-table": { "type": "object", "description": "A table attribute within a metadata template group. Identified by type: tableAttribute. Contains nested fields in tableFieldsDenormalized.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "ed0a638f-1b96-4bb0-a77d-022c92e89d84" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Events" }, "type": { "type": "string", "description": "Always `tableAttribute` for this schema.", "enum": [ "tableAttribute" ], "example": "tableAttribute" }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "events" }, "attributeOrder": { "type": "integer", "description": "Display order within the group.", "example": 4 }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "isSingleRow": { "type": "boolean", "description": "Whether the table is limited to a single row.", "example": false }, "isSmartTable": { "type": "boolean", "description": "Whether the table is a smart table.", "example": false }, "tableNameVisible": { "type": "boolean", "description": "Whether the table name is displayed.", "example": false }, "dateFormat": { "type": "string", "description": "Always \"N/A\" for table attributes.", "example": "N/A" }, "tableFieldsDenormalized": { "type": "array", "description": "Denormalized fields within the table. Each field follows a similar structure to top-level attributes but uses `fieldOrder` instead of `attributeOrder`. Field types within a table can be `text`, `controlledVocabulary`, `date`, or `cascadeAttribute`.", "items": { "oneOf": [ { "$ref": "#/components/schemas/template-attribute-table-field-textbox" }, { "$ref": "#/components/schemas/template-attribute-table-field-controlled-vocabulary" }, { "$ref": "#/components/schemas/template-attribute-table-field-date" }, { "$ref": "#/components/schemas/template-attribute-table-field-cascade" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/template-attribute-table-field-textbox", "controlledVocabulary": "#/components/schemas/template-attribute-table-field-controlled-vocabulary", "date": "#/components/schemas/template-attribute-table-field-date", "cascadeAttribute": "#/components/schemas/template-attribute-table-field-cascade" } } } } }, "required": [ "id", "name", "type", "searchField", "tableFieldsDenormalized" ] }, "template-attribute-cascade": { "type": "object", "description": "A cascade attribute within a metadata template group. Identified by type: cascadeAttribute. Contains nested cascade levels in cascadeFieldsDenormalized.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the attribute.", "example": "5ec692fc-e03b-43f9-a3e4-966565bd6812" }, "name": { "type": "string", "description": "Display name of the attribute.", "example": "Country Region Cascade" }, "type": { "type": "string", "description": "Always `cascadeAttribute` for this schema.", "enum": [ "cascadeAttribute" ], "example": "cascadeAttribute" }, "searchField": { "type": "string", "description": "System-generated search index field name.", "example": "country_region_cascade" }, "attributeOrder": { "type": "integer", "description": "Display order within the group.", "example": 5 }, "visible": { "type": "boolean", "description": "Whether the attribute is visible.", "example": true }, "dateFormat": { "type": "string", "description": "Always \"N/A\" for cascade attributes.", "example": "N/A" }, "cascadeMapId": { "type": "string", "format": "uuid", "description": "ID of the cascade map defining the hierarchy.", "example": "cba796a5-7a5a-4efc-b3d8-03bfee5663f1" }, "cascadeNameVisible": { "type": "boolean", "description": "Whether the cascade name is displayed.", "example": true }, "cascadeFieldsDenormalized": { "type": "array", "description": "Ordered list of cascade levels. Each level is a controlled vocabulary field with a `cascadeOrder` indicating its depth in the hierarchy.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the cascade level field." }, "name": { "type": "string", "description": "Display name of the cascade level." }, "type": { "type": "string", "description": "Type of the cascade level field (typically `controlledVocabulary`).", "enum": [ "controlledVocabulary" ] }, "subType": { "type": "string", "description": "Sub-type of the cascade level field.", "enum": [ "textBox" ] }, "searchField": { "type": "string", "description": "System-generated search index field name." }, "cascadeOrder": { "type": "integer", "description": "Zero-based depth in the cascade hierarchy." }, "visible": { "type": "boolean" }, "required": { "type": "boolean" }, "readonly": { "type": "boolean" }, "facetable": { "type": "boolean" }, "sensitive": { "type": "boolean" }, "typeahead": { "type": "boolean" }, "featured": { "type": "boolean" }, "isRestricted": { "type": "boolean" }, "isMultipleSelect": { "type": "boolean" }, "sortByHitCount": { "type": "boolean" }, "dateFormat": { "type": "string" }, "tooltip": { "type": "string" }, "techMetaMapping": { "type": "string" }, "controlledVocabularyId": { "type": "string", "format": "uuid", "description": "ID of the controlled vocabulary for this cascade level." } } } } }, "required": [ "id", "name", "type", "searchField", "cascadeMapId", "cascadeFieldsDenormalized" ] }, "metadata-template-detail": { "type": "object", "description": "Full metadata template object with denormalized groups and attributes.", "properties": { "templateId": { "type": "string", "format": "uuid", "description": "Unique ID of the metadata template.", "example": "0a5d6320-7e8c-43f3-b32a-7a32bcf2b261" }, "templateName": { "type": "string", "description": "Display name of the metadata template.", "example": "Product Shot" }, "createdEpoch": { "type": "integer", "description": "Creation timestamp in Unix milliseconds.", "example": 1774035316248 }, "lastUpdatedEpoch": { "type": "integer", "description": "Last updated timestamp in Unix milliseconds.", "example": 1779214564563 }, "templateType": { "type": "array", "description": "Template type classifications.", "items": { "type": "string", "enum": [ "default", "asset", "action" ] }, "example": [ "default" ] }, "template": { "type": "object", "description": "The denormalized template structure containing metadata groups.", "properties": { "metadataGroups": { "type": "array", "description": "Ordered list of metadata groups with fully resolved attributes.", "items": { "type": "object", "properties": { "groupOrder": { "type": "integer", "description": "Display order of this group within the template.", "example": 1 }, "metadataGroupName": { "type": "string", "description": "Display name of the group.", "example": "Product Information" }, "metadataGroupSearchField": { "type": "string", "description": "System-generated slug for the group.", "example": "product_information" }, "securityPermissions": { "type": "array", "description": "Security permissions applied to this group. Empty array if none.", "items": { "type": "object" } }, "metadataAttributes": { "type": "array", "description": "Ordered list of attributes in this group. The shape of each attribute varies by `type`:\n- **text** (subType: textBox) — includes `length`, `typeahead`, `techMetaMapping`. Max 250 chars, supports faceting.\n- **text** (subType: textArea) — includes `length`, `techMetaMapping`. Max 10000 chars. Cannot be facetable or typeahead.\n- **controlledVocabulary** — includes `controlledVocabularyId`, `isMultipleSelect`\n- **date** — includes `dateFormat`\n- **tableAttribute** — includes `tableFieldsDenormalized`, `isSingleRow`, `isSmartTable`, `tableNameVisible`\n- **cascadeAttribute** — includes `cascadeMapId`, `cascadeFieldsDenormalized`, `cascadeNameVisible`", "items": { "oneOf": [ { "$ref": "#/components/schemas/template-attribute-text" }, { "$ref": "#/components/schemas/template-attribute-controlled-vocabulary" }, { "$ref": "#/components/schemas/template-attribute-date" }, { "$ref": "#/components/schemas/template-attribute-table" }, { "$ref": "#/components/schemas/template-attribute-cascade" } ], "discriminator": { "propertyName": "type", "mapping": { "text": "#/components/schemas/template-attribute-text", "controlledVocabulary": "#/components/schemas/template-attribute-controlled-vocabulary", "date": "#/components/schemas/template-attribute-date", "tableAttribute": "#/components/schemas/template-attribute-table", "cascadeAttribute": "#/components/schemas/template-attribute-cascade" } } } } } } } } } } }, "metadata-vocabulary-list": { "type": "object", "description": "Paginated list of controlled vocabularies.", "properties": { "hitCount": { "type": "integer", "description": "Total number of vocabularies matching the search criteria.", "example": 14 }, "results": { "type": "array", "description": "Array of vocabulary summary objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the vocabulary.", "example": "34abed31-4546-4f15-ae07-3d22b9b056d5" }, "name": { "type": "string", "description": "Display name of the vocabulary.", "example": "Usage Mediums" }, "searchField": { "type": "string", "description": "System-generated slug used for search indexing. Permanent once created.", "example": "usage_mediums" }, "type": { "type": "string", "nullable": true, "description": "Vocabulary type. `null` when never set.", "example": "controlledVocabulary" }, "featured": { "type": "boolean", "nullable": true, "description": "System-assigned. `null` if never set.", "example": null }, "valueCount": { "type": "integer", "description": "Number of values defined on the vocabulary. Always present, including when `values[]` is omitted.", "example": 12 }, "values": { "type": "array", "description": "The vocabulary's values. Only present when the `include` query parameter contains `values`.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "Digital" } } } }, "createdBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the vocabulary's creator. `null` for platform-owned vocabularies.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1770714900000 }, "createdDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date.", "example": "2026-02-10T09:15:00Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the last user to update the vocabulary. `null` when never updated.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1771432800000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last-updated date.", "example": "2026-02-18T16:40:00Z" }, "inUse": { "type": "boolean", "description": "Derived from `usedIn` — `true` when any `usedIn` category is non-empty.", "example": true }, "usedIn": { "type": "object", "description": "Where the vocabulary is currently referenced.", "properties": { "metadataAttributes": { "type": "array", "description": "Attributes backed by this vocabulary. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "99ff8765-aa11-bb22-cc33-dd44ee55ff66" }, "name": { "type": "string", "example": "Asset Category" } } } }, "metadataCascades": { "type": "array", "description": "Cascades that reference this vocabulary. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" }, "name": { "type": "string", "example": "Region Cascade" } } } }, "metadataTables": { "type": "array", "description": "Tables that reference this vocabulary. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83" }, "name": { "type": "string", "example": "Store Locations Table" } } } }, "metadataGroups": { "type": "array", "description": "Groups that reference this vocabulary. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42" }, "name": { "type": "string", "example": "Retail Assets" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that reference this vocabulary. Empty array if none.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84" }, "name": { "type": "string", "example": "Retail Asset Template" } } } } } } } } } } }, "metadata-cascade-list": { "type": "object", "description": "Paginated list of metadata cascades.", "properties": { "hitCount": { "type": "integer", "description": "Total number of cascades matching the search criteria.", "example": 9 }, "results": { "type": "array", "description": "Array of cascade summary objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the cascade.", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" }, "name": { "type": "string", "description": "Display name of the cascade.", "example": "Region Cascade" }, "searchField": { "type": "string", "description": "System-generated slug. Permanent once created.", "example": "region_cascade" }, "nameVisible": { "type": "boolean", "description": "Whether the cascade name is visible when rendered on an asset.", "example": true }, "featured": { "type": "boolean", "nullable": true, "description": "System-assigned. `null` if never set. Blocks deletion when `true`.", "example": null }, "levelCount": { "type": "integer", "description": "Number of levels defined on the cascade (maximum 4). Always present.", "example": 2 }, "levels": { "type": "array", "description": "Ordered levels. Only present when the `include` query parameter contains `levels`; same shape as `GET /metadata/cascades/{id}`'s `levels`.", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid", "description": "Id of the controlled-vocabulary attribute backing this level's dropdown values.", "example": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" }, "attributeName": { "type": "string", "description": "Denormalized display name of the backing attribute.", "example": "Continent" }, "order": { "type": "integer", "description": "Zero-based level position.", "example": 0 } } } }, "valueCount": { "type": "integer", "description": "Total value nodes across the whole tree, all levels combined. Always present.", "example": 12 }, "values": { "type": "array", "description": "Full nested value tree. Only present when the `include` query parameter contains `values`; same shape as `GET /metadata/cascades/{id}`'s `values`.", "items": { "type": "object", "description": "A cascade value node. `children` nest in this same shape, up to the cascade's defined number of levels (maximum 4).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Always empty — the maximum nesting depth (4 levels) has been reached.", "items": {} } } } } } } } } } } } } }, "createdBy": { "type": "string", "format": "uuid", "description": "User-profile id of the cascade's creator.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1770714900000 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-02-10T09:15:00Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User-profile id of the last user to update the cascade.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1771432800000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated date.", "example": "2026-02-18T16:40:00Z" }, "inUse": { "type": "boolean", "description": "Derived from `usedIn` — `true` when any of `usedIn.metadataTables`, `usedIn.metadataGroups`, or `usedIn.metadataTemplates` is non-empty.", "example": true }, "usedIn": { "type": "object", "description": "Where the cascade is currently referenced. A cascade's only direct relationship is being used as a column inside a Table. `metadataGroups` is a derived, transitive rollup of every group reached through that table's own group membership (Table → group). `metadataTemplates` is a further derived, transitive rollup of every template reached through that group's own template membership (group → template).", "properties": { "metadataTables": { "type": "array", "description": "Tables that directly use this cascade as a column.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83" }, "name": { "type": "string", "example": "Store Locations Table" } } } }, "metadataGroups": { "type": "array", "description": "Groups that transitively reach this cascade through a table that uses it.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42" }, "name": { "type": "string", "example": "Retail Assets" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that transitively reach this cascade through a table that uses it.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84" }, "name": { "type": "string", "example": "Retail Asset Template" } } } } } } } } } } }, "create-metadata-cascade": { "type": "object", "description": "JSON object defining the cascade to create — its level schema and initial value tree, in one call. Required: `name`, `levels`. Optional: `nameVisible` (defaults to `true`), `searchField` (creates a featured cascade), `values` (may be omitted to create an empty cascade).", "properties": { "name": { "type": "string", "description": "Display name for the new cascade.", "example": "Region Cascade" }, "searchField": { "type": "string", "description": "Optional. When supplied, the cascade is created as featured, using this value as its permanent search field slug instead of a server-generated one.", "example": "region_cascade" }, "nameVisible": { "type": "boolean", "description": "Whether the cascade name is visible when rendered on an asset. Defaults to `true`.", "default": true, "example": true }, "levels": { "type": "array", "description": "Level schema for the cascade. Maximum 4 entries. Each `attributeId` must reference an existing, single-select controlled-vocabulary attribute.", "items": { "type": "object", "required": [ "order", "attributeId" ], "properties": { "order": { "type": "integer", "description": "Zero-based level position.", "example": 0 }, "attributeId": { "type": "string", "format": "uuid", "description": "Id of the existing, single-select controlled-vocabulary attribute backing this level.", "example": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" } } } }, "values": { "type": "array", "description": "Initial value tree. May be omitted to create an empty cascade and populate values later via update. `id` is client-generated so a multi-level tree can be submitted in one request. Nesting depth via `children` must not exceed `levels.length` (and therefore can never exceed 4). No two nodes in the submitted tree may share the same `id`.", "items": { "type": "object", "description": "A cascade value node. `children` nest in this same shape, up to the cascade's defined number of levels (maximum 4). `id` is client-generated and must be unique within the submitted tree.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Always empty — the maximum nesting depth (4 levels) has been reached.", "items": {} } } } } } } } } } } } } } }, "required": [ "name", "levels" ] }, "metadata-cascade-detail": { "type": "object", "description": "Full detail of a metadata cascade, as returned by `GET /metadata/cascades/{id}`. Everything here is returned unconditionally — there is no `include` option on this endpoint.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the cascade.", "example": "b7e41f2a-6c9d-4a17-8f3b-2d5c8a0e3f61" }, "name": { "type": "string", "description": "Display name of the cascade.", "example": "Region Cascade" }, "searchField": { "type": "string", "description": "System-generated slug. Permanent once created.", "example": "region_cascade" }, "levels": { "type": "array", "description": "Ordered levels, fixed at creation. Always present here — unconditional, unlike the list endpoint where it's only included via `?include=levels`.", "items": { "type": "object", "properties": { "attributeId": { "type": "string", "format": "uuid", "description": "Id of the controlled-vocabulary attribute backing this level's dropdown values.", "example": "a29f3e1c-7b4d-4f8a-9c2e-5d1b8f6a3c70" }, "attributeName": { "type": "string", "description": "Denormalized display name of the backing attribute.", "example": "Continent" }, "order": { "type": "integer", "description": "Zero-based level position; kept as an explicit field rather than implied by array order, since asset metadata can store level references out of order.", "example": 0 } } } }, "nameVisible": { "type": "boolean", "description": "Whether the cascade name is visible when rendered on an asset.", "example": true }, "featured": { "type": "boolean", "nullable": true, "description": "System-assigned. `null` if never set. Blocks deletion when `true`.", "example": null }, "createdBy": { "type": "string", "format": "uuid", "description": "User-profile id of the cascade's creator.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1770714900000 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-02-10T09:15:00Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User-profile id of the last user to update the cascade.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1771432800000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated date.", "example": "2026-02-18T16:40:00Z" }, "usedIn": { "type": "object", "description": "Where the cascade is currently referenced. A cascade's only direct relationship is being used as a column inside a Table. `metadataGroups` is a derived, transitive rollup of every group reached through that table's own group membership (Table → group). `metadataTemplates` is a further derived, transitive rollup of every template reached through that group's own template membership (group → template).", "properties": { "metadataTables": { "type": "array", "description": "Tables that directly use this cascade as a column.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "e91a4c7d-3f8b-4e26-9a1d-7c5b0e9f2a83" }, "name": { "type": "string", "example": "Store Locations Table" } } } }, "metadataGroups": { "type": "array", "description": "Groups that transitively reach this cascade through a table that uses it.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3b8f1e6a-2d9c-4a75-8e0f-7c1b5d3a9e42" }, "name": { "type": "string", "example": "Retail Assets" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that transitively reach this cascade through a table that uses it.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84" }, "name": { "type": "string", "example": "Retail Asset Template" } } } } } }, "values": { "type": "array", "description": "Full nested value tree, returned untruncated — always present here (unconditional, same as `levels`; the list endpoint only includes it via `?include=values`). Depth is bounded at 4 levels, but breadth is not — a level with hundreds of sibling values can still make this a large payload.", "items": { "type": "object", "description": "A cascade value node. `children` nest in this same shape, up to the cascade's defined number of levels (maximum 4).", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Nested child values at the next level. Empty array for a leaf node.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Value node id.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "source": { "type": "string", "nullable": true, "description": "Present only when this level's attribute is a Dynamic Controlled Vocabulary (a CV composed from other CVs) — holds the search field of the underlying source CV this value was copied from. `null` for a value sourced from an ordinary controlled vocabulary. System-computed only; never client-supplied.", "example": null }, "children": { "type": "array", "description": "Always empty — the maximum nesting depth (4 levels) has been reached.", "items": {} } } } } } } } } } } } } } } }, "update-metadata-cascade": { "type": "object", "description": "JSON object updating an existing cascade's `name`, `nameVisible`, and/or its full value tree. At least one of `name`, `nameVisible`, `values` is required. `levels` and `featured` are never accepted.", "properties": { "name": { "type": "string", "description": "New display name for the cascade.", "example": "Global Region Cascade" }, "nameVisible": { "type": "boolean", "description": "Whether the cascade name is visible when rendered on an asset.", "example": false }, "values": { "type": "array", "description": "Full replacement of the value tree — not a diff. Nodes omitted from the request are removed. Same shape, depth, and duplicate-id rules as create.", "items": { "type": "object", "description": "A cascade value node. `children` nest in this same shape, up to the cascade's defined number of levels (maximum 4). `id` is client-generated and must be unique within the submitted tree.", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Nested child values at the next level. Omit or leave empty for a leaf node.", "items": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Client-generated id for this value node, unique within the submitted tree.", "example": "f3a8c1e5-9d24-4b7a-8e6f-1c3a9d5e2b74" }, "name": { "type": "string", "description": "Display value.", "example": "North America" }, "children": { "type": "array", "description": "Always empty — the maximum nesting depth (4 levels) has been reached.", "items": {} } } } } } } } } } } } } }, "expectedLastUpdatedEpoch": { "type": "integer", "description": "Optional optimistic-concurrency check. If provided and it does not match the cascade's current `lastUpdatedEpoch`, the update is rejected with `409`.", "example": 1771432800000 } } }, "metadata-table-list": { "type": "object", "description": "Paginated list of metadata tables.", "properties": { "hitCount": { "type": "integer", "description": "Total number of tables matching the search criteria.", "example": 24 }, "results": { "type": "array", "description": "Array of table summary objects.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the table.", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" }, "name": { "type": "string", "description": "Display name of the table.", "example": "Store Locations Table" }, "searchField": { "type": "string", "description": "System-generated slug. Permanent once created.", "example": "store_locations_table" }, "isSingleRow": { "type": "boolean", "description": "Fixed at creation.", "example": false }, "isSmartTable": { "type": "boolean", "description": "Fixed at creation.", "example": false }, "convertTo": { "type": "string", "nullable": true, "enum": [ "smart" ], "description": "Set to `smart` while a standard-to-smart conversion is pending \"Apply Changes\"; `null` otherwise.", "example": null }, "featured": { "type": "boolean", "nullable": true, "description": "System-assigned. `null` if never set. Blocks deletion when `true`.", "example": null }, "fieldCount": { "type": "integer", "description": "Number of columns configured on the table. Full column list is only available via `GET /metadata/tables/{id}`.", "example": 3 }, "createdBy": { "type": "string", "format": "uuid", "description": "User-profile id of the table's creator.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1772704800000 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-03-05T10:00:00Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User-profile id of the last user to update the table.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1773325200000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated date.", "example": "2026-03-12T14:20:00Z" }, "inUse": { "type": "boolean", "description": "Derived from `usedIn` — `true` when either `usedIn.metadataGroups` or `usedIn.metadataTemplates` is non-empty.", "example": true }, "usedIn": { "type": "object", "description": "Where the table is currently referenced. Does not include an `attributes` category — attributes never reference a table; a table contains attributes as its columns, never the reverse.", "properties": { "metadataGroups": { "type": "array", "description": "Groups that reference this table.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" }, "name": { "type": "string", "example": "Product Information" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that reference this table.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84" }, "name": { "type": "string", "example": "Retail Asset Template" } } } } } } } } } } }, "create-metadata-table": { "type": "object", "description": "JSON object defining the table to create. Required: `name`, `isSingleRow`, `tableFields`. Optional: `isSmartTable` (defaults to `false`).", "properties": { "name": { "type": "string", "description": "Display name for the new table. Maximum 32 characters.", "example": "Store Locations Table" }, "isSingleRow": { "type": "boolean", "description": "Whether the table is single-row. Permanent once set.", "example": false }, "isSmartTable": { "type": "boolean", "description": "Whether the table is a smart table. Defaults to `false`. Permanent once set; mutually exclusive with `isSingleRow: true`. Subject to a 25-per-customer smart-table cap, enforced at creation time.", "default": false, "example": false }, "tableFields": { "type": "array", "description": "Columns for the table. Between 1 and 12 effective columns — a plain or controlled-vocabulary field counts as 1, a cascade field counts as its number of levels. Each `fieldId` must reference an existing attribute or cascade (never another table); no two entries may reference the same `fieldId`.", "items": { "type": "object", "required": [ "fieldOrder", "fieldId" ], "properties": { "fieldOrder": { "type": "integer", "description": "Display order.", "example": 1 }, "fieldId": { "type": "string", "format": "uuid", "description": "Id of the existing attribute or cascade backing this column.", "example": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61" } } } } }, "required": [ "name", "isSingleRow", "tableFields" ] }, "metadata-table-detail": { "type": "object", "description": "Full detail of a metadata table, returned by `GET /metadata/tables/{id}`, `POST /metadata/tables`, `PATCH /metadata/tables/{id}`, and `POST /metadata/tables/{id}/convert-to-smart`. Everything from the list endpoint's row shape except `fieldCount`, plus the full `tableFields` column list.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the table.", "example": "e6a91f4c-8b2d-4a17-9c6e-3f5a8d1b7c92" }, "name": { "type": "string", "description": "Display name of the table.", "example": "Store Locations Table" }, "searchField": { "type": "string", "description": "System-generated slug. Permanent once created.", "example": "store_locations_table" }, "isSingleRow": { "type": "boolean", "description": "Fixed at creation.", "example": false }, "isSmartTable": { "type": "boolean", "description": "Fixed at creation. Remains `false` while a standard-to-smart conversion is pending (see `convertTo`).", "example": false }, "convertTo": { "type": "string", "nullable": true, "enum": [ "smart" ], "description": "Set to `smart` while a standard-to-smart conversion is pending \"Apply Changes\"; `null` otherwise.", "example": null }, "featured": { "type": "boolean", "nullable": true, "description": "System-assigned. `null` if never set. Blocks deletion when `true`.", "example": null }, "tableFields": { "type": "array", "description": "Ordered columns. Stays flat even for a cascade-backed column — no nested expansion of the cascade's own levels here.", "items": { "type": "object", "properties": { "fieldOrder": { "type": "integer", "description": "Display order.", "example": 1 }, "fieldId": { "type": "string", "format": "uuid", "description": "Id of the attribute or cascade backing this column.", "example": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61" }, "fieldName": { "type": "string", "description": "Denormalized display name.", "example": "Store Name" }, "fieldType": { "type": "string", "description": "The column's underlying type, so the UI can render the right control/icon without a second lookup.", "example": "textbox", "enum": [ "textbox", "textarea", "date", "dropdown", "cascade" ] } } } }, "createdBy": { "type": "string", "format": "uuid", "description": "User-profile id of the table's creator.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1772704800000 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-03-05T10:00:00Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User-profile id of the last user to update the table.", "example": "8f2a5c91-4e6d-4b83-9a17-6c0d3e8b2f45" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1773325200000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last-updated date.", "example": "2026-03-12T14:20:00Z" }, "usedIn": { "type": "object", "description": "Where the table is currently referenced. Does not include an `attributes` category — attributes never reference a table; a table contains attributes as its columns, never the reverse.", "properties": { "metadataGroups": { "type": "array", "description": "Groups that reference this table.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "52ce0235-02cc-46f6-8bdb-05238c76bf83" }, "name": { "type": "string", "example": "Product Information" } } } }, "metadataTemplates": { "type": "array", "description": "Templates that reference this table.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "9c4a7f21-8e63-4b0d-a175-2f6c9b3e0d84" }, "name": { "type": "string", "example": "Retail Asset Template" } } } } } } } }, "update-metadata-table": { "type": "object", "description": "JSON object updating an existing table's `name` and/or its column list. At least one of `name`, `tableFields` is required. `isSingleRow`, `isSmartTable`, and `featured` are permanently fixed and are never accepted here.", "properties": { "name": { "type": "string", "description": "New display name for the table. Maximum 32 characters. Does not regenerate `searchField`.", "example": "Store Locations Table (US)" }, "tableFields": { "type": "array", "description": "Full replacement of the column list — not a diff. Same effective-column-count, valid-reference, and no-duplicate-`fieldId` rules as create.", "items": { "type": "object", "required": [ "fieldOrder", "fieldId" ], "properties": { "fieldOrder": { "type": "integer", "description": "Display order.", "example": 1 }, "fieldId": { "type": "string", "format": "uuid", "description": "Id of the existing attribute or cascade backing this column.", "example": "d3f8a1c2-6b4e-4a17-9c3f-2e7b5d0a8f61" } } } } } }, "create-request": { "type": "object", "properties": { "title": { "type": "string", "example": "New Marketing Upload Request", "description": "Title of the upload request." }, "metadataTemplateId": { "type": "string", "format": "uuid", "example": "18bb2566-0a9c-45c7-825b-4a14d3c71e42", "description": "ID of the metadata template to apply to Request." }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" }, "example": [ "1ef152a4-281a-4f02-8fb0-1204ae050705" ], "description": "Array of security template IDs to apply to Request." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "13e6991b-5c11-40b8-95ff-9e9013de44b5" } } } }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ] ] } ] } }, "required": [ "title", "metadataTemplateId", "securityTemplateIds", "assets", "metadata" ] }, "create-request-2": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Id returned after creating the Request. This is uniquely identifies the request.", "example": "e3beae4b-338c-4fda-8bf7-be3a8d82a230" } } }, "get-request": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique ID of the Request", "example": "e3beae4b-338c-4fda-8bf7-be3a8d82a230" }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cd0caff5-2756-4d7c-a43d-a926a81fa9b8", "description": "Unique identifier for the asset." }, "assignedTo": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tenovos User Id for the user who the request is assigned to.", "example": "986caca7-b6d4-478b-9850-acf54b25c6d5" }, "firstName": { "type": "string", "description": "First Name of the user who the request is assigned to.", "example": "Galvin" }, "lastName": { "type": "string", "description": "Last Name of the user who the request is assigned to.", "example": "Belson" }, "email": { "type": "string", "description": "Email address used for the user account who the request is assigned to.", "example": "galvin.belson@huli.com" } } } } } }, "assetCount": { "type": "integer", "example": 2, "description": "Provides a count of the number of assets belonging to the Request." }, "title": { "type": "string", "description": "The Title of the request.", "example": "Galvin's Upload Request" }, "type": { "type": "string", "description": "Identifies the type of the Request", "example": "Upload" }, "status": { "type": "string", "example": "In Progress", "description": "The status of the Request in it's current state." }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tenovos User Id for the user who the request was submitted by.", "example": "556caca7-b6d4-478b-9850-bcf54b25c6b2" }, "firstName": { "type": "string", "description": "First Name of the user who the request was submitted by.", "example": "Erlich" }, "lastName": { "type": "string", "description": "Last Name of the user who the request was submitted by.", "example": "Bachman" }, "email": { "type": "string", "description": "Email address used for the user account who the request was submitted by.", "example": "erlich.backman@piedpipper.com" } } }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "id": "a4e75e25-2baf-4204-b6c8-b8fa67b9d4ab", "name": "Release Date", "searchField": "release_date", "value": "01/01/2024" }, { "id": "d9cb7f63-6b58-4531-8704-41e95c416c95", "searchField": "product_name", "name": "Product", "value": "HooliDocs" }, { "id": "b8d955a3-10ab-456e-91c4-b0a878786d48", "searchField": "usage_table", "name": "Usage Table", "value": [ [ { "id": "b4047831-3921-4684-a434-1bb68214c111", "searchField": "usage_category", "name": "Usage Category", "value": "E-Commerce" }, { "id": "bcf51509-8460-4ecf-ad9d-67f09a5682f6", "searchField": "usage_length", "name": "Usage Length", "value": "12 months" } ] ] } ] } } }, "update-request": { "type": "object", "properties": { "assignedTo": { "type": "string", "format": "email", "example": "admin@tenovos.com", "description": "Email of the user to whom the assets are assigned." }, "status": { "type": "string", "example": "In Progress", "description": "Use this property to update the status of the Request." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "cd0caff5-2756-4d7c-a43d-a926a81fa9b8", "description": "Unique identifier for the asset." }, "assignedTo": { "type": "string", "format": "email", "example": "ctc-admin@tenovos.com", "description": "Email of the user assigned to the asset." }, "status": { "type": "string", "example": "Rejected", "description": "Current status of the asset (e.g., Approved, Rejected)." }, "note": { "type": "string", "example": "Test Note", "description": "Additional notes about the asset." }, "rejectionReason": { "type": "string", "example": "Invalid Asset Metadata", "description": "Reason for rejection, if applicable." } } } } } }, "list-requests": { "type": "object", "properties": { "from": { "type": "integer", "example": 0, "description": "Starting index for each request, used in conjunction with the limit property to paginate results." }, "limit": { "type": "integer", "example": 100, "maximum": 100, "minimum": 1, "description": "Number of results to return per request/page." }, "type": { "type": "string", "example": "Upload", "description": "Optional property to filter the response to only specific Request Types." }, "status": { "type": "string", "example": "In Progress", "description": "Optional property to filter the response to only Requests with a specific status." }, "includes": { "type": "array", "description": "Optional array to provide **searchField** values for the metadata attributes on the Requests that you'd like returned in addition to the standard Request data.", "example": [ "asset_identifier", "primary_sku_entry", "pi_table_prim_product_info" ] } } }, "list-requests-2": { "type": "object", "properties": { "total": { "type": "integer", "example": 54, "description": "total number of results based on search criteria." }, "results": { "type": "array", "minItems": 0, "maxItems": 100, "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique Identifier for the Request in Tenovos.", "example": "09a52f4f-1d6d-4f62-a263-877acac65ff9" }, "title": { "type": "string", "description": "The Title of the request.", "example": "Galvin's Upload Request" }, "type": { "type": "string", "description": "Identifies the type of the Request", "example": "Upload" }, "assetCount": { "type": "integer", "example": 2, "description": "Provides a count of the number of assets belonging to the Request." }, "assignees": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tenovos User Id for the user who the request is assigned to.", "example": "986caca7-b6d4-478b-9850-acf54b25c6d5" }, "firstName": { "type": "string", "description": "First Name of the user who the request is assigned to.", "example": "Galvin" }, "lastName": { "type": "string", "description": "Last Name of the user who the request is assigned to.", "example": "Belson" }, "email": { "type": "string", "description": "Email address used for the user account who the request is assigned to.", "example": "galvin.belson@huli.com" } } } }, "submittedBy": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Tenovos User Id for the user who the request was submitted by.", "example": "556caca7-b6d4-478b-9850-bcf54b25c6b2" }, "firstName": { "type": "string", "description": "First Name of the user who the request was submitted by.", "example": "Erlich" }, "lastName": { "type": "string", "description": "Last Name of the user who the request was submitted by.", "example": "Bachman" }, "email": { "type": "string", "description": "Email address used for the user account who the request was submitted by.", "example": "erlich.backman@piedpipper.com" } } }, "status": { "type": "string", "example": "In Progress", "description": "The status of the Request in it's current state." }, "metadata": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/attribute" }, { "$ref": "#/components/schemas/table" } ] }, "example": [ { "name": "Release Date", "value": "01/01/2024" }, { "name": "Product", "value": "HooliDocs" }, { "name": "Usage Table", "value": [ [ { "name": "Usage Category", "value": "E-Commerce" }, { "name": "Usage Length", "value": "12 months" } ] ] } ] } } } } } }, "role": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The Tenovos unique identifier assigned to the Role", "example": "e171b93a-9f42-4a78-8845-b60f3e783c3c" }, "name": { "type": "string", "description": "The user provided label/name of the Role.", "example": "Creative Producer" } }, "required": [ "id", "name" ] }, "roles": { "type": "array", "items": { "$ref": "#/components/schemas/role" }, "minItems": 1, "maxItems": 100, "uniqueItems": true }, "security-privileges": { "type": "object", "description": "Object containing the id and name for each available security privilege. Privileges are applied at the role level for each user.", "properties": { "privileges": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the role privilege.", "example": "9a265a28-14ed-472b-943b-e0f2b3f15c3d" }, "name": { "type": "string", "description": "The name of the role privilege", "example": "Download" }, "status": { "type": "string", "description": "Status of the role privilege for the customer account.", "example": "enabled", "enum": [ "enabled", "disabled" ] } } } } } }, "search": { "type": "object", "properties": { "searchTerm": { "type": "array", "description": "Comma separated array of search term values.", "items": { "type": "string" }, "example": [ "Gilfoyle", "Dinesh", "Erlich" ] }, "filters": { "type": "array", "description": "List of facet-style filter attributes and values, applied in addition to any `searchTerm` entries. Uses the same `(Attribute Name:\"Value\")` syntax as `searchTerm`, including the `-` prefix to exclude Assets matching a value. For example `(Asset Type:-\"Logo\")` returns Assets that do **not** have an Asset Type of Logo, while `(Asset Type:\"Logo\")` returns only Assets that do.", "items": { "type": "string" }, "example": [ "(Asset Type:\"Logo\")", "(Department:-\"Sales\")" ] }, "from": { "type": "integer", "description": "Search offset from which index search will start", "example": 0 }, "limit": { "type": "integer", "description": "Limits the number of results that are returned.", "maximum": 100, "example": 50 }, "includes": { "type": "array", "description": "System metadata fields, such as Metadata Template ID, \nshould be entered using camel case (ie, metadataTemplateId). Custom metadata fields should be entered by their attribute search term, prefixed by metadataDocument. For example, to retrieve an attribute called Published Channel, a user \nwould include \"metadataDocument.published_channel\" in the includes array. Fields included in this array will be returned in an object called 'metadataDocument' if those attributes exist on the asset.", "items": { "type": "string" }, "example": [ "metadataTemplateId", "metadataDocument.asset_description", "metadataDocument.file_size", "metadataDocument.compression_type" ] }, "includeDeleted": { "type": "boolean", "description": "Flag to denote whether or not to include Deleted assets in the result", "items": { "type": "boolean", "example": true } }, "includeVersions": { "type": "boolean", "description": "Flag to denote whether or not to include prior versions of the asset in the result", "items": { "type": "boolean", "example": false } }, "sortBy": { "type": "array", "items": { "type": "object", "properties": { "metadataDefinitionSearchField": { "type": "string", "description": "Sort the result set according to specified attributes by metadata search field name", "example": "lastUpdatedEpoch" }, "order": { "type": "string", "description": "Sort Order", "example": "desc", "enum": [ "asc", "desc" ] } } } }, "operation": { "type": "string", "description": "Operation between search terms", "example": "AND", "enum": [ "AND", "OR" ] }, "aggregations": { "type": "boolean", "description": "Boolean field to indicate whether or not to return filter menu aggregation counts for the search term. Set to false to significant improve speed and reduce payload size.", "example": false }, "keywordSearchField": { "type": "string", "description": "Specified Search Target. Valid values are - filename, assetId, metadata, content", "example": "filename", "enum": [ "filename", "assetId", "metadata", "content" ] }, "relevancy": { "type": "boolean", "description": "If the 'relevancy' field is passed as true, this will negate the operation selection used \nin legacy search and will leverage the relevancy search matching. When relevancy is set to true, \nthe 'metadataDefinitionSearchField' field within the sortBy object should be set to 'relevance', and the 'order' field should be set to 'desc'.", "example": true } } }, "search-result": { "type": "object", "description": "Asset object returned in the search results.", "properties": { "createdEpoch": { "type": "integer", "description": "Date the asset was created in epoch format. Creation time in milliseconds.", "example": 1727724108027 }, "metadataDocument": { "type": "object", "description": "Metadata on the asset based on the *includes* array items that was requested with the search request. Dynamic metadata properties based on the request.", "additionalProperties": { "type": "string" } }, "fileId": { "type": "string", "description": "Asset File ID that uniquely identifies the content associated to this asset.", "example": "445c273a-235f-4d3b-8397-567f02f312e0" }, "filename": { "type": "string", "example": "gilfoyle_anton.png" }, "originalFileId": { "type": "string", "description": "The ID of the original version of the file", "example": "2d69d72f-91be-4aeb-9d62-4fbd3759e451" }, "createdBy": { "type": "string", "example": "d6197e75-74e2-4a81-9c39-429148ab27a1" }, "objectId": { "type": "string", "description": "Asset Object ID. Also referred to as Asset ID.", "example": "c5e24f53-cb77-4882-927c-0e8dddf5f7c9" }, "customerId": { "type": "string", "description": "Customer ID of Created By User's Account", "example": 1588091945182 }, "metadataTemplateId": { "type": "string", "description": "ID of the metadata template the asset is assigned to", "example": "f5a66fac-7e81-44c1-b6eb-20997c559982" }, "renditionsDocument": { "$ref": "#/components/schemas/renditions" }, "securityTemplateIds": { "type": "array", "description": "List of ID(s) of Security Template(s) that are applied to the asset", "items": { "type": "string", "format": "uuid", "example": "2d331840-50a0-4dc1-bc65-56151bf58a39" } } } }, "facets": { "type": "string", "description": "string containing JSON of filter facets", "example": "{\"Company\":{\"buckets\":[{\"key\":\"Pied Piper\",\"doc_count\":47},{\"key\":\"Hooli\",\"doc_count\":4}]}" }, "search-2": { "type": "object", "properties": { "total": { "type": "integer", "example": 1, "description": "Provides the total number of search results based on the search criteria provided." }, "results": { "type": "array", "description": "List of asset objects matching the search criteria.", "items": { "$ref": "#/components/schemas/search-result" } }, "facets": { "$ref": "#/components/schemas/facets" } } }, "security-permissions": { "type": "object", "description": "Object containing the id and name for each available security permission. Permissions are applied at the group level for each security template.", "properties": { "permissions": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the security permission.", "example": "9a265a28-14ed-472b-943b-e0f2b3f15c3d" }, "name": { "type": "string", "description": "The name of the security permission", "example": "Download" } } } } } }, "create-security-template": { "type": "object", "description": "Domain body describing a security, rights, or access template as a list of groups and the permissions granted to each. The server derives the stored `template_document` and `security_template_denormalized` structures from this shape — callers never build them directly.", "required": [ "name" ], "properties": { "name": { "type": "string", "description": "Display name of the template. Trimmed, non-empty, maximum 75 characters. Must be unique per customer.", "example": "Confidential" }, "type": { "type": "string", "description": "Template classification. Defaults to `security-template`. Set only at creation; immutable thereafter.", "enum": [ "security-template", "rights-template", "access-template" ], "default": "security-template", "example": "security-template" }, "groups": { "type": "array", "description": "Groups to assign to the template, each with the permissions granted to it. Defaults to `[]`. Duplicate group IDs are rejected.", "default": [], "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Group ID. Must exist for the authenticated customer.", "example": "f22dccbc-6032-4279-9f19-d5dc91d9757e" }, "permissionIds": { "type": "array", "description": "IDs of the permissions granted to this group. An empty array means the group is present but grants nothing. Defaults to `[]`.", "default": [], "items": { "type": "string", "format": "uuid" }, "example": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ] } } } } } }, "security-template-detail": { "type": "object", "description": "Full detail of a security, rights, or access template, including a page of its groups and their granted permissions.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the template.", "example": "a9380047-07d7-48aa-b4b7-474d00f0f428" }, "name": { "type": "string", "description": "Display name of the template.", "example": "Confidential" }, "type": { "type": "string", "description": "Template classification. Set at creation and immutable thereafter.", "enum": [ "security-template", "rights-template", "access-template" ], "example": "security-template" }, "groupCount": { "type": "integer", "description": "Total number of groups on the template, across all pages.", "example": 2 }, "permissionCount": { "type": "integer", "description": "Total number of permissions granted across all groups, including the watermark permission.", "example": 3 }, "createdBy": { "type": "string", "format": "uuid", "description": "User ID of the template's creator.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1773070355217 }, "createdDate": { "type": "string", "format": "date-time", "description": "ISO 8601 creation date.", "example": "2026-03-09T15:32:35.217Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "User ID of the user who last updated the template.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update. Pass this value back as `expectedLastUpdatedEpoch` on `PATCH` to guard against concurrent edits.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 last updated date.", "example": "2026-03-09T15:32:35.217Z" }, "groups": { "type": "object", "description": "Page of groups assigned to the template.", "properties": { "totalCount": { "type": "integer", "description": "Total number of groups on the template, across all pages.", "example": 2 }, "items": { "type": "array", "description": "Groups on this page.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the group.", "example": "f22dccbc-6032-4279-9f19-d5dc91d9757e" }, "name": { "type": "string", "description": "Display name of the group.", "example": "Marketing" }, "permissions": { "type": "array", "description": "Permissions evaluated against this group. Present only when `includePermissions` is `true`.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "31bdde6b-1a2c-4d5e-8f90-1234567890ab" }, "name": { "type": "string", "example": "View" }, "isPermitted": { "type": "boolean", "description": "Whether this group is granted the permission.", "example": true } } } } } } }, "pageInfo": { "type": "object", "description": "Pagination metadata for `groups.items`.", "properties": { "hasNextPage": { "type": "boolean", "description": "Whether more groups exist beyond this page.", "example": false }, "nextCursor": { "type": "string", "nullable": true, "description": "Cursor for the next page of groups. Pass as `groupCursor` on the next request. Null if no more pages.", "example": null } } } } } } }, "update-security-template": { "type": "object", "description": "Partial update body. Only the fields provided are changed; omitted fields are left untouched. At least one of `name` or `groups` must be present. `type` is not an updatable field — including it in the body returns a `400`.", "properties": { "name": { "type": "string", "description": "Updated display name. Same validation as creation (trimmed, non-empty, maximum 75 characters); re-checked for uniqueness if changed.", "example": "Confidential - Marketing" }, "groups": { "type": "array", "description": "When present, this is a full replacement of the template's group/permission set — the service recomputes both stored columns from it. Omit to leave the current groups untouched.", "items": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Group ID. Must exist for the authenticated customer.", "example": "f22dccbc-6032-4279-9f19-d5dc91d9757e" }, "permissionIds": { "type": "array", "description": "IDs of the permissions granted to this group. An empty array means the group is present but grants nothing.", "items": { "type": "string", "format": "uuid" }, "example": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ] } } } }, "expectedLastUpdatedEpoch": { "type": "integer", "description": "Optional optimistic-concurrency guard. When provided, it is compared against the template's current `lastUpdatedEpoch`; a mismatch is rejected with `409` and `code: STALE_UPDATE`. Omit for last-write-wins.", "example": 1773070355217 } } }, "create-security-role": { "type": "object", "description": "JSON object defining the security role to create. Required: `name`. Optional: `consentForm` (defaults to `\"\"`), `privileges` (defaults to `[]`).", "properties": { "name": { "type": "string", "description": "Display name of the role. 1-32 characters after trimming. Must be unique per customer, case-insensitively.", "example": "Compression Engineer" }, "consentForm": { "type": "string", "description": "Consent text a user must accept to hold this role. Defaults to an empty string. `null` is treated as absent.", "example": "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm and follow all platform security policies." }, "privileges": { "type": "array", "description": "Privilege ids to grant to the role. Defaults to `[]`. De-duplicated case-insensitively. Each id must be a syntactically valid UUID and must exist and be enabled in the customer's privilege catalog.", "items": { "type": "string", "format": "uuid" }, "example": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ] } }, "required": [ "name" ] }, "security-role-detail": { "type": "object", "description": "Full detail of a security role, including its consent form, granted privileges, and everywhere it's currently referenced.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the role.", "example": "6c15af83-d4a9-4772-875a-1c8a2bb1688f" }, "name": { "type": "string", "description": "Display name of the role.", "example": "Creative Producer" }, "consentForm": { "type": "string", "description": "Consent text a user must accept to hold this role.", "example": "By accepting this role you agree to uphold Pied Piper's brand and confidentiality guidelines when producing creative assets." }, "privilegeCount": { "type": "integer", "description": "Number of privileges granted to the role.", "example": 2 }, "privileges": { "type": "array", "description": "Flat array of permitted privilege ids only. Denied/unpermitted entries in the underlying role document are not surfaced.", "items": { "type": "string", "format": "uuid" }, "example": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab", "9e187a4e-cfe4-419e-8c6c-2509e4bf400b" ] }, "userCount": { "type": "integer", "description": "Number of users currently assigned this role.", "example": 12 }, "usedIn": { "type": "object", "description": "Everywhere the role is currently referenced.", "properties": { "presets": { "type": "array", "description": "Upload or filter presets whose `role_ids` include this role.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3a9f1c2e-8b4d-4f6a-9c1e-2b3a4c5d6e7f" }, "name": { "type": "string", "example": "Pied Piper Marketing Upload" }, "type": { "type": "string", "enum": [ "upload", "filter" ], "example": "upload" } } } } } }, "createdBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the role's creator. `null` if the row has no recorded author.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1734000000000 }, "createdDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date, derived from `createdEpoch`.", "example": "2024-12-12T12:00:00.000Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the last user to update the role. `null` if the row has no recorded author.", "example": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1755600000000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last-updated date, derived from `lastUpdatedEpoch`.", "example": "2025-08-19T12:00:00.000Z" } }, "required": [ "id", "name" ] }, "update-security-role": { "type": "object", "description": "JSON object with the fields to change. At least one of `name`, `consentForm`, or `privileges` is required. `privileges`, when present, fully replaces the existing set rather than merging with it.", "properties": { "name": { "type": "string", "description": "New display name for the role. 1-32 characters after trimming. Renaming to the role's own current name (even differing only by case) is not a collision.", "example": "Senior Compression Engineer" }, "consentForm": { "type": "string", "description": "New consent text for the role.", "example": "By accepting this role you agree to safeguard Pied Piper's proprietary middle-out compression algorithm, follow all platform security policies, and report suspected leaks immediately." }, "privileges": { "type": "array", "description": "Full replacement set of privilege ids. An empty array clears all privileges. Omitting this field leaves the role's stored privileges untouched.", "items": { "type": "string", "format": "uuid" }, "example": [ "31bdde6b-1a2c-4d5e-8f90-1234567890ab" ] }, "expectedLastUpdatedEpoch": { "type": "integer", "description": "Optional optimistic-concurrency guard. If supplied and it doesn't match the role's current `lastUpdatedEpoch`, the write is rejected with `409` and `code: STALE_UPDATE`.", "example": 1755600000000 } } }, "create-security-user-group": { "type": "object", "description": "JSON object defining the security user group to create. `name` is the only accepted field.", "properties": { "name": { "type": "string", "description": "Display name of the group. 1-255 characters after trimming. Must be unique per customer, case-insensitively. `type` is not an accepted input field — the created group is always `type: security`.", "example": "Pied Piper Engineering" } }, "required": [ "name" ] }, "security-user-group-detail": { "type": "object", "description": "Full detail of a security user group, including everywhere it's currently referenced. This shape only ever describes `type: security` groups — a `type: channel` group is fully inaccessible through this API and 404s exactly as if it didn't exist.", "properties": { "id": { "type": "string", "description": "Unique ID of the group. Opaque string — ids are generated as UUIDs, but this isn't a format guarantee.", "example": "group-hooli-corporate" }, "name": { "type": "string", "description": "Display name of the group.", "example": "Hooli Corporate" }, "type": { "type": "string", "description": "Always `security` for a group returned by this API. Response-only — never an accepted input field on create or update.", "enum": [ "security" ], "example": "security" }, "userCount": { "type": "integer", "description": "Number of users currently in this group.", "example": 24 }, "usedIn": { "type": "object", "description": "Everywhere the group is currently referenced.", "properties": { "securityTemplates": { "type": "array", "description": "Security templates that still reference this group.", "items": { "type": "object", "properties": { "id": { "type": "string", "example": "tmpl-hooli-apac-viewers" }, "name": { "type": "string", "example": "Hooli APAC Viewers" } } } } } }, "createdBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the group's creator. `null` if the row has no recorded author.", "example": "dc63db1b-1e63-43bc-877e-418931b6895c" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1734000000000 }, "createdDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 creation date, derived from `createdEpoch`.", "example": "2024-12-12T12:00:00.000Z" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "nullable": true, "description": "User-profile id of the last user to update the group. `null` if the row has no recorded author.", "example": "a5ae4577-8940-4ca9-bf2c-b1b65b4306ec" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1755600000000 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "nullable": true, "description": "ISO 8601 last-updated date, derived from `lastUpdatedEpoch`.", "example": "2025-08-19T12:00:00.000Z" } }, "required": [ "id", "name", "type" ] }, "bulk-create-security-user-groups": { "type": "object", "description": "JSON object listing the security user group names to create in one all-or-nothing batch. Either every name is created, or none are — there is no partial success.", "properties": { "names": { "type": "array", "description": "Non-empty array of group names to create. Maximum 50 entries per request. Each name follows the same rules as single-create (1-255 characters after trimming). A name repeated within the same request (case-insensitively, after trimming) is rejected — it is not silently de-duplicated.", "minItems": 1, "maxItems": 50, "items": { "type": "string" }, "example": [ "Hooli Corporate", "Hooli EMEA", "Hooli APAC" ] } }, "required": [ "names" ] }, "update-security-user-group": { "type": "object", "description": "JSON object to rename the group. Unlike a role's PATCH, `name` is always required here, not \"at least one of several fields.\" `type` is not an accepted field.", "properties": { "name": { "type": "string", "description": "New display name for the group. 1-255 characters after trimming.", "example": "Hooli Corporate EMEA" }, "expectedLastUpdatedEpoch": { "type": "integer", "description": "Optional optimistic-concurrency guard. If supplied and it doesn't match the group's current `lastUpdatedEpoch`, the write is rejected with `409` and `code: STALE_UPDATE`.", "example": 1755600000000 } }, "required": [ "name" ] }, "user-list": { "type": "object", "description": "Offset-paginated list of users for the authenticated customer.", "properties": { "users": { "type": "array", "description": "Users on this page.", "items": { "type": "object", "properties": { "userId": { "type": "string", "format": "uuid", "description": "Unique ID of the user.", "example": "7d675ef0-f423-11e9-8071-89c0c4052141" }, "customerId": { "type": "string", "description": "Parent customer ID.", "example": "1234567890" }, "emailId": { "type": "string", "format": "email", "description": "User email address.", "example": "erlich.bachman@piedpiper.com" }, "firstName": { "type": "string", "description": "User first name.", "example": "Erlich" }, "lastName": { "type": "string", "description": "User last name.", "example": "Bachman" }, "roleId": { "type": "string", "format": "uuid", "description": "ID of the user's assigned role.", "example": "7d5620e0-f423-11e9-8071-89c0c4052141" }, "roleName": { "type": "string", "description": "Display name of the user's assigned role.", "example": "Admin" }, "status": { "type": "string", "description": "Account status.", "enum": [ "enabled", "disabled", "pendingApproval" ], "example": "enabled" }, "groups": { "type": "array", "description": "Groups the user belongs to.", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid", "description": "Unique ID of the group.", "example": "7d6207c0-f423-11e9-8071-89c0c4052141" }, "groupName": { "type": "string", "description": "Display name of the group.", "example": "Marketing" } } }, "example": [ { "groupId": "7d6207c0-f423-11e9-8071-89c0c4052141", "groupName": "Marketing" } ] }, "connectUser": { "type": "boolean", "description": "Whether the user can access Tenovos Connect.", "example": true }, "connectRole": { "type": "string", "nullable": true, "description": "The user's Tenovos Connect role. Null when `connectUser` is `false`.", "example": "Admin" }, "userName": { "type": "string", "nullable": true, "description": "The username of the Tenovos user, created by the administrator or user at account creation. Can be null for federated user accounts.", "example": "erlich.bachman" }, "phone": { "type": "string", "example": "15551234565" }, "contact": { "type": "string", "description": "The person designated as the sponsor/point of contact for this user.", "example": "Richard Hendricks" }, "country": { "type": "string", "description": "The country in which the Tenovos user is located.", "example": "USA" }, "company": { "type": "string", "description": "The company that the Tenovos user works for.", "example": "Pied Piper" }, "friendlyName": { "type": "string", "description": "A \"friendlier\" version of the username. Used in the UI display and provided by the user.", "example": "Erlich Bachman" }, "createdEpoch": { "type": "integer", "description": "Unix timestamp (ms) of creation.", "example": 1690000000000 }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the last update.", "example": 1700000000000 } } } }, "pageInfo": { "type": "object", "properties": { "from": { "type": "integer", "description": "Offset of the first result on this page.", "example": 0 }, "limit": { "type": "integer", "description": "Maximum number of results requested per page.", "example": 100 }, "total": { "type": "integer", "description": "Total number of users matching the search and filters, before pagination.", "example": 842 }, "hasNextPage": { "type": "boolean", "description": "Whether more matching users exist beyond this page.", "example": true } } } } }, "adaptive-templates": { "type": "array", "items": { "type": "object", "properties": { "childProductIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "renditionsDocument": { "type": "object", "properties": { "fpo": { "type": "string", "format": "url", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/Template_Store_Asset_1-fpo.png" }, "aiRendition": { "type": "string", "format": "url", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/aiRendition.png" }, "imagePreviewLarge": { "type": "string", "format": "url", "description": "Rendition of the original asset in PNG format with a size of 1000x1000", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/09789d41-0b7b-4c13-b060-41b5e479f844-1000x1000.png" }, "imageThumb": { "type": "string", "format": "url", "description": "Rendition of the original asset in PNG format with a size of 200x200", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/09789d41-0b7b-4c13-b060-41b5e479f844-200x200.png" }, "imagePreview": { "type": "string", "format": "url", "description": "Rendition of the original asset in PNG format with a size of 700x700", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/09789d41-0b7b-4c13-b060-41b5e479f844-700x700.png" }, "mezzaninePreview": { "type": "string", "format": "url", "description": "Rendition of the original asset in PNG format with a size of 3000x3000", "example": "https://tenant.tenovos.io/1623232044386/74216a5c-386d-47d6-854c-dc28535116cf/Template_Store_Asset_1-3000x3000.png" }, "height": { "type": "integer", "format": "int32", "example": 1080 }, "width": { "type": "integer", "format": "int32", "example": 1920 } } }, "avamTags": { "type": "array", "items": { "type": "string" } }, "lockType": { "type": "array", "items": { "type": "string" } }, "objectType": { "type": "string" }, "digitalAssetIds": { "type": "array", "items": { "type": "string" } }, "fileState": { "type": "string" }, "technicalMetadataDocument": { "type": "object", "properties": { "image_metadata": { "type": "object" }, "tenovos_metadata": { "type": "object", "properties": { "fileName": { "type": "string" }, "fileSize": { "type": "string" }, "fileSizeInBytes": { "type": "integer", "format": "int32" }, "MD5Checksum": { "type": "string" } } } } }, "customerId": { "type": "string", "description": "Unique Identifier for the Tenovos Cusotmer" }, "lastUpdatedEpoch": { "type": "integer", "format": "int64" }, "metadataTemplateId": { "type": "string" }, "objectId": { "type": "string" }, "metadataDocument": { "type": "object", "properties": { "system_created_epoch": { "type": "string" }, "template_title": { "type": "string" }, "description": { "type": "string" }, "system_content_type": { "type": "string" }, "system_is_federated": { "type": "string" }, "system_security_templates": { "type": "array", "items": { "type": "string" } }, "title": { "type": "string" }, "system_metadata_templates": { "type": "string" }, "web2print_template_name": { "type": "string" }, "system_mime_type": { "type": "string" }, "web2print_job_name": { "type": "string" }, "system_checksum": { "type": "string" }, "system_last_updated_by": { "type": "string" }, "system_skip_transcode": { "type": "string" }, "system_created_date": { "type": "integer", "format": "int64" }, "system_created_by": { "type": "string" }, "web2print_job_xml": { "type": "string" }, "web2printlink": { "type": "string" }, "system_match": { "type": "string" }, "system_last_updated_date": { "type": "integer", "format": "int64" } } }, "metadataState": { "type": "string" }, "lastUpdatedBy": { "type": "string", "format": "uuid", "description": "Unique Identifier of the Tenovos user who last updated the template." }, "originalFileId": { "type": "string", "format": "uuid" }, "securityTemplateIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "currentVersion": { "type": "string", "description": "Indicates whether or not this template/asset is the latest version available", "example": "Y", "enum": [ "Y", "N" ] }, "versionNumber": { "type": "integer", "format": "int64" }, "filename": { "type": "string" }, "createdEpoch": { "type": "integer", "format": "int64" }, "technicalMetadataText": { "type": "string" }, "createdBy": { "type": "string", "format": "uuid", "description": "Unique Identifier of the Tenovos user who created the template/asset" }, "AITags": { "type": "array", "items": { "type": "string" } }, "fileId": { "type": "string", "format": "uuid" }, "securityTemplateDenormalized": { "type": "array", "description": "Contains an array of objects, one for each Tenovos user group assigned permissions on the Security Template applied to the asset, identified by user goup id, and includes an array of persmission identifiers for each user group.", "items": { "type": "object", "properties": { "groupId": { "type": "string", "format": "uuid" }, "permissions": { "type": "array", "items": { "type": "string", "format": "uuid" } } } } } } } }, "launch-template": { "type": "object", "properties": { "templateId": { "type": "string", "format": "uuid", "required": [ "templateId" ], "x-nullable": false } } }, "launch": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "example": "https://templates.tenovos.io/launch?jobName=somejob&deleteJob=true&externalLaunch=true" } } }, "webhook": { "type": "object", "properties": { "description": { "type": "string", "x-nullable": false, "required": [ "description" ], "description": "You must provide a description for the subscription.", "minLength": 5, "maxLength": 100, "example": "Notify System X for All Assets Created" }, "eventTypes": { "type": "array", "x-nullable": false, "required": [ "event" ], "description": "One of the available [event types](https://api.tenovos.com/developer-portal/webhooks/event-types/) listed", "example": [ "asset.created", "asset.updated", "asset.downloaded", "asset.deleted" ] }, "url": { "type": "string", "x-nullable": false, "required": [ "url" ], "format": "url", "description": "A webhook target is usually an open and public url that listens for webhook notification messages. Tenovos signs every webhook message to ensure the security and authenticity of all webhooks being sent. In addition, Tenovos supports HTTP Basic Authentication and using an authentication token in headers. Choose one of these authentication methods as part of your target payload.", "example": "https://yourendpoint.com" }, "rateLimit": { "type": "integer", "x-nullable": false, "example": 200 } } }, "webhooks": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "x-nullable": false, "description": "Identifier of the event" } } }, "endpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "x-nullable": false, "description": "Identifier of the event" }, "description": { "type": "string", "x-nullable": false, "required": [ "description" ], "description": "You must provide a description for the subscription.", "minLength": 5, "maxLength": 100, "example": "Notify System X for All Assets Created" }, "disabled": { "type": "boolean", "example": false, "description": "Indicates whether or not the endpoint subscription is disabled or not" }, "url": { "type": "string", "x-nullable": false, "required": [ "url" ], "format": "url", "description": "A webhook target is usually an open and public url that listens for webhook notification messages. Tenovos signs every webhook message to ensure the security and authenticity of all webhooks being sent. In addition, Tenovos supports HTTP Basic Authentication and using an authentication token in headers. Choose one of these authentication methods as part of your target payload.", "example": "https://yourendpoint.com" }, "eventTypes": { "type": "array", "x-nullable": false, "required": [ "event" ], "description": "One of the available [event types](https://api.tenovos.com/developer-portal/webhooks/event-types/) listed", "example": [ "asset.created", "asset.updated", "asset.downloaded", "asset.deleted" ] }, "rateLimit": { "type": "integer", "x-nullable": false, "example": 200 } } }, "eventType": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the Event Type. Determined by Tenovos.", "example": "asset.created" }, "description": { "type": "string", "x-nullable": false, "required": [ "description" ], "description": "You must provide a description for the event type.", "minLength": 5, "maxLength": 100, "example": "Event when a new asset in Tenovos is created." }, "createdDate": { "type": "string", "format": "date", "description": "The Date and time the Event Type was created." } } }, "webhook-oauthCreate": { "type": "object", "properties": { "clientId": { "type": "string", "required": [ "clientId" ], "description": "Customer generated clientId from OAuth server/provider", "example": "FbhKdCwuiItoSSRJpKXc6cjhpJFVy7JbB" }, "clientSecret": { "type": "string", "required": [ "clientSecret" ], "description": "Customer generated client secret from OAuth server/provider", "example": "ZtjtpXP7p5SdUwNYu1JT9xfQobecM0i5UGOu_F5BU6DdAOPFLZDz7r0xObogttPG" }, "tokenUrl": { "type": "string", "format": "url", "required": [ "tokenUrl" ], "description": "Customer provided https url for obtaining access tokens from the customers OAuth server/provider", "example": "https://yourdomain.provider/oauth/token" }, "extraParams": { "type": "object", "description": "Optional collection of key value pair parameters which may be required depending on OAuth provider.", "example": { "audience": "https://api.tenovos.io/v1" } }, "scope": { "type": "array", "description": "Optional array of strings for included scopes if configured by the customer on their OAuth server/provider for the generated client", "example": [ "Assets, Users" ] } } }, "remove-rights-association": { "type": "object", "description": "JSON object identifying the two objects participating in the association to remove. Required: `primary`, `secondary`, each with `objectId` and `objectType`.", "properties": { "primary": { "type": "object", "description": "One of the two objects participating in the association.", "required": [ "objectId", "objectType" ], "properties": { "objectId": { "type": "string", "format": "uuid", "description": "Unique ID of the object.", "example": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c" }, "objectType": { "type": "string", "description": "Type of the object.", "enum": [ "RM - Agreement", "RM - Project", "RM - Entity", "RM - Right" ], "example": "RM - Agreement" } } }, "secondary": { "type": "object", "description": "The other of the two objects participating in the association.", "required": [ "objectId", "objectType" ], "properties": { "objectId": { "type": "string", "format": "uuid", "description": "Unique ID of the object.", "example": "42ac8e81-8113-49fd-977b-a2001ad3d7c8" }, "objectType": { "type": "string", "description": "Type of the object.", "enum": [ "RM - Agreement", "RM - Project", "RM - Entity", "RM - Right" ], "example": "RM - Project" } } } }, "required": [ "primary", "secondary" ] }, "rights-association-removal": { "type": "object", "description": "Result of a rights-association removal. `removed.relationships` lists every relationship removed by the operation; `removed.objects` is empty unless the association was an `Agreement -> Right` containment, in which case it holds the soft-deleted Right.", "properties": { "status": { "type": "string", "enum": [ "success" ], "example": "success" }, "removed": { "type": "object", "properties": { "relationships": { "type": "array", "description": "All relationships removed by the operation, including any downstream relationships justified solely by the removed association.", "items": { "type": "object", "properties": { "primaryId": { "type": "string", "format": "uuid", "description": "Object ID on the primary side of the removed relationship.", "example": "6543a6a0-4b5d-4a54-94a8-e6c7733fe92c" }, "secondaryId": { "type": "string", "format": "uuid", "description": "Object ID on the secondary side of the removed relationship.", "example": "42ac8e81-8113-49fd-977b-a2001ad3d7c8" }, "linkType": { "type": "string", "description": "The type of relationship that was removed.", "example": "rm-project-agreement" } } } }, "objects": { "type": "array", "description": "Objects removed as a consequence of the association removal. Empty for `Project <-> Agreement` and `Agreement <-> Entity` removals. Contains the soft-deleted Right for `Agreement -> Right` removals.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique ID of the removed object.", "example": "9b1f3c2a-1234-4a54-94a8-e6c7733fe92c" }, "objectType": { "type": "string", "description": "Type of the removed object.", "example": "RM - Right" }, "status": { "type": "string", "description": "Lifecycle status of the object after removal.", "enum": [ "deleted" ], "example": "deleted" }, "lastUpdatedEpoch": { "type": "integer", "description": "Unix timestamp (ms) of the soft-delete.", "example": 1773070355217 }, "lastUpdatedDate": { "type": "string", "format": "date-time", "description": "ISO 8601 date of the soft-delete.", "example": "2026-03-09T15:32:35.217Z" } } } } } } } } }, "examples": { "impersonateUserExample": { "value": { "username": "john.wick" } }, "newTokenExample": { "value": { "username": "john.wick@tenovos.com", "password": "m#P52s@ap$V" } }, "refreshTokenExample": { "value": { "session": { "accessToken": "yJraWQiOiJITk5BbmN6bW1NajFaMUlGN", "refreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2" } } }, "expireTokenExample": { "value": { "endpointUrl": "https://endpoint.url/v1", "clientId": "abcdefghijklmnop1234567890", "userPoolId": "us-east-1_123456789", "username": "john.wick", "session": { "authorization": "eyJraWQiOiJqQWNzNDFBdFBEcXdKTVN6Y0dzV01SNFR0T3hETDhcL3dtOW9qQ0JOWVdqcz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJhdWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwiZW1haWxfdmVyaWZpZWQiOmZhbHNlLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImlkIiwiYXV0aF90aW1lIjoxNjEzNzUyODE3LCJpc3MiOiJodHRwczpcL1wvY29nbml0by1pZHAudXMtZWFzdC0xLmFtYXpvbmF3cy5jb21cL3VzLWVhc3QtMV9PU2dRdlRhVEEiLCJjb2duaXRvOnVzZXJuYW1lIjoiamVmZiIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJlbWFpbCI6ImplZmZAdGVub3Zvcy5jb20ifQ.kzu1AddXc-HIopmmsxnnXjDiKXhOLox6P2Hx5HCg0gzupbjW9hjbMWVl0NIZRgrLJIEkYjTl9zRUre_QpiJdeVdluMVPLi6OfMUy8XskeqrOAUFDr3nqrkt99uR-LSrVd_hI8NSGvRPXEcWXV6A35Nq8_xZ8tHHlWEanGhtNcEPzgWa1JU1LdQPDCtixgwQGhroevX2TByGC_yfbimn9l5JeveQGyWKNIfvUPR9zLu2g8bPgCzCUroNWU1QRh1o-p1-8lMVwyROl3mIiCfSTo_QwtLArcFTJi5MyMsWCwWHXV", "accessToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBMjU2R0NNIiwiYWxnIjoiUlNBLU9BRVAifQ.jkuKuQVDhGxbX04I3iczTCioh9ah2MA90YkOcY7DTyLS94XCvS_JpOhUSHhk70uM_ZNxLCU00OtahFm7Ktc-Zw_21qjuA40yf9Uf0KcQok5DEbv-9-_j8F4PAdChaS8Cok_-SjUoZmbiIgC-uF601vcczTHgC2SLs4FiOubdc-3tVjQrt6sf0k_W3cBBR-ajbYrDYMdHiJGEtetod88bO1WYJlSWhSddHXkjWOYE0-x3flkDswYJkEq1FKpc1lgqaeoVGShJ90H4S9Yj_FS9vHd0Yq8pwOUkCjIr_P3xFK4d9pRtEc35gkQ3QMbE1Nx93srzUx2rkI75_J2Hf3IltA.jlAjOx1FRapys-J-.YfjwTEQMsnp1wPXkKab_NvA_6lZp15ur2zNUEuX0NqC4hfQ6kbzzQXOl_nLujNwLI8YqqNgLni3l4Eu-luxHDCM2fHvjVaL6_ULJ9VThkBlkJYmxFQZX8c20EPWa1IBH630EPKslFNwPgYT113", "refreshToken": "eyJraWQiOiJITk5BbmN6bW1NajFaMUlGNXE3SXdzM3RvbE1QWnFYRjBWVFVzUGQyTnc4PSIsImFsZyI6IlJTMjU2In0.eyJzdWIiOiI0ZmUwZTVhZi0yMjU1LTRiZDUtYjAwYS0yM2FkMTIxZTA2ZjIiLCJldmVudF9pZCI6IjQ1YWI3YzJjLTJjYWUtNDE2MS1hYmE4LWMyMmIxZmQ5NGViYyIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiYXdzLmNvZ25pdG8uc2lnbmluLnVzZXIuYWRtaW4iLCJhdXRoX3RpbWUiOjE2MTM3NTI4MTcsImlzcyI6Imh0dHBzOlwvXC9jb2duaXRvLWlkcC51cy1lYXN0LTEuYW1hem9uYXdzLmNvbVwvdXMtZWFzdC0xX09TZ1F2VGFUQSIsImV4cCI6MTYxMzc1NjQyMCwiaWF0IjoxNjEzNzUyODIwLCJqdGkiOiI3NWJjZWYzZi03Njg3LTQ5MjgtOTY2Zi05MzM0MmQ0MjFmYjkiLCJjbGllbnRfaWQiOiI3c201amlsZG5iZnJyOGNncTNrZWRpZW83IiwidXNlcm5hbWUiOiJqZWZmIn0.COepDhay_VaqCHJwNOT" } } }, "ControlledVocabularyNameChange": { "summary": "Change Name", "value": { "name": "Hooli Employees" } }, "ControlledVocabularyAdd": { "summary": "Add Value", "value": { "add": [ "Jared Dunn" ] } }, "ControlledVocabularyUpdate": { "summary": "Update Values", "value": { "update": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" } ] } }, "ControlledVocabularyDelete": { "summary": "Delete Values", "value": { "delete": [ "e1dd92fa-ed3a-4038-b837-c7f4d6395f16" ] } }, "ControlledVocabularyNameChangeResp": { "summary": "Change Name", "value": { "name": { "metadataDefinitionId": "83559f3a-93a8-4eba-a709-0bca6497450e", "metadataDefinitionName": "Hooli Employees", "metadataDefinitionSearchField": "hooli_employees", "metadataDefinitionType": "controlledVocabulary", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1781815426034, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1781815985807, "metadataDocument": { "values": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" }, { "valueId": "b0dd4f37-5fc7-4db3-9d60-31aad8d1fbaa", "valueName": "Jared Dunn" }, { "valueId": "2284a68f-fa52-4fb4-a6ef-3fe96501644b", "valueName": "Erlich Bachman" }, { "valueId": "713a4dd3-02c6-4b3a-81f5-a4d6e793ed5f", "valueName": "Gilfoyle" }, { "valueId": "e1f7f8a2-7885-4593-b09a-bf1a650a042f", "valueName": "Dinesh Chugtai" } ] }, "securityTemplateIds": [] } } }, "ControlledVocabularyAddResp": { "summary": "Add Value", "value": { "add": { "metadataDefinitionId": "83559f3a-93a8-4eba-a709-0bca6497450e", "metadataDefinitionName": "Hooli Employees", "metadataDefinitionSearchField": "hooli_employees", "metadataDefinitionType": "controlledVocabulary", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1781815426034, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1781815705525, "metadataDocument": { "values": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" }, { "valueId": "b0dd4f37-5fc7-4db3-9d60-31aad8d1fbaa", "valueName": "Jared Dunn" } ] }, "securityTemplateIds": [] } } }, "ControlledVocabularyUpdateResp": { "summary": "Update Values", "value": { "update": { "metadataDefinitionId": "83559f3a-93a8-4eba-a709-0bca6497450e", "metadataDefinitionName": "Hooli Employees", "metadataDefinitionSearchField": "hooli_employees", "metadataDefinitionType": "controlledVocabulary", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1781815426034, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1781815613553, "metadataDocument": { "values": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" } ] }, "securityTemplateIds": [] } } }, "ControlledVocabularyDeleteResp": { "summary": "Delete Values", "value": { "delete": { "metadataDefinitionId": "83559f3a-93a8-4eba-a709-0bca6497450e", "metadataDefinitionName": "Hooli Employees", "metadataDefinitionSearchField": "hooli_employees", "metadataDefinitionType": "controlledVocabulary", "customerId": "1739271540099", "createdBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "createdEpoch": 1781815426034, "lastUpdatedBy": "dc63db1b-1e63-43bc-877e-418931b6895c", "lastUpdatedEpoch": 1781815791126, "metadataDocument": { "values": [ { "valueId": "2926d594-9c03-4aa1-91a8-76a0b6e67e4f", "valueName": "Richard Hendricks" }, { "valueId": "b0dd4f37-5fc7-4db3-9d60-31aad8d1fbaa", "valueName": "Jared Dunn" } ] }, "securityTemplateIds": [] } } }, "CreateAsset": { "value": { "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "metadata": [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66aea6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": [ { "valueId": "7d6f4e30-f423-11e9-8071-89c0c4052141" } ] }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionTableValue": [ [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66ada6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" } ] ] } ], "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "filename": "apples.jpg" } }, "CreateNewAssetVersion": { "value": { "originalFileId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "metadata": [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66aea6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": [ { "valueId": "7d6f4e30-f423-11e9-8071-89c0c4052141" } ] }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionTableValue": [ [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66ada6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" } ] ] } ], "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "filename": "apples.jpg" } }, "MultipartUpload": { "value": { "metadataTemplateId": "ea6eb24d-adef-4080-bd02-f64f567c437f", "metadata": [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66aea6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": [ { "valueId": "7d6f4e30-f423-11e9-8071-89c0c4052141" } ] }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionTableValue": [ [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66ada6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" } ] ] } ], "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052141", "9f2a1e4b-7c3d-4a8f-b6e5-1d0c9a8b7e6f", "3e7f2a91-5b4c-48d6-a1c3-8f6e0d2b4a75" ], "filename": "apples.jpg", "fileSize": 182989737790 } }, "AssetCreateResponse": { "value": { "filename": "apples.jpg", "objectId": "e55bdb0c-022b-475d-9e26-9d74552e1e81", "fileId": "ecc0d79a-e5cc-41aa-852d-1d9e0da62739", "originalFileId": "ecc0d79a-e5cc-41aa-852d-1d9e0da62739", "url": "https://contentstore3.amazonaws.com/masters/919f33e2-dc03-4627-ab7b-642a5f1d11ae/apples.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAYNV%2F20210221%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210221T023210Z&X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIFz62IeetD0q9EPtTeRxCSZEcNMqsuGVqK9UmK&X-Amz-Signature=e03d60e8299af92664a0ea8f9be78c50c8dd28f88520b0c2b7d0073b36511ce5&X-Amz-SignedHeaders=host%3Bx-amz-meta-objectid&x-amz-meta-objectid=2c1d0732-31a7-4800-bbd7-3fb05c222549" } }, "MultipartUploadResponse": { "value": { "filename": "apples.jpg", "objectId": "e55bdb0c-022b-475d-9e26-9d74552e1e81", "fileId": "ecc0d79a-e5cc-41aa-852d-1d9e0da62739", "originalFileId": "ecc0d79a-e5cc-41aa-852d-1d9e0da62739", "uploadId": "gR5XHJZpuDv8UizdpSGuwONje0GbMHnCWXS5zTTVkyVINURV6iraWLhpM7Sy7oy65utAgPcm2FfM4fRp4oVga4ggEzD811aS1tke_F0iIIXX1kV7m6UouytsNE0oL8fzo2Zr2JCqwRyhFTXp98zjdQ", "urls": [ { "partNumber": 1, "url": "https://contentstore3.amazonaws.com/masters/919f33e2-dc03-4627-ab7b-642a5f1d11ae/apples.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAYNV%2F20210221%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210221T023210Z&X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIFz62IeetD0q9EPtTeRxCSZEcNMqsuGVqK9UmK&X-Amz-Signature=e03d60e8299af92664a0ea8f9be78c50c8dd28f88520b0c2b7d0073b36511ce5&X-Amz-SignedHeaders=host%3Bx-amz-meta-objectid&x-amz-meta-objectid=2c1d0732-31a7-4800-bbd7-3fb05c222549" }, { "partNumber": 2, "url": "https://contentstore3.amazonaws.com/masters/919f33e2-dc03-4627-ab7b-642a5f1d11ae/apples.jpg?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=ASIAYNV%2F20210221%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20210221T023210Z&X-Amz-Expires=86400&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEKv%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIFz62IeetD0q9EPtTeRxCSZEcNMqsuGVqK9UmK&X-Amz-Signature=e03d60e8299af92664a0ea8f9be78c50c8dd28f88520b0c2b7d0073b36511ce5&X-Amz-SignedHeaders=host%3Bx-amz-meta-objectid&x-amz-meta-objectid=2c1d0732-31a7-4800-bbd7-3fb05c222549" } ] } }, "CreateCollection": { "value": { "collectionType": "secured", "name": "Best of the month", "collectionDocument": [ "0fcb5eb4-5e0e-4ffa-8780-9206a0f833f1", "ecc0d79a-e5cc-41aa-852d-1d9e0da62739" ], "metadataTemplateId": "ea6eb24d-adef-4380-bd02-f64f567c437f", "metadataDocument": [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66aea6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": [ { "valueId": "7d6f4e30-f423-11e9-8071-89c0c4052141" } ] }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionTableValue": [ [ { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff0b959a", "metadataDefinitionValue": "Photo" }, { "metadataDefinitionId": "dfeb57c1-b149-4b15-920f-3f40ff3423ad1", "metadataDefinitionValue": { "valueId": "3fa85f64-5717-4562-b3fc-2c963f66ada6" } }, { "metadataDefinitionId": "3229e863-022b-4365-afe6-e9aa3807c386", "metadataDefinitionValue": "02/10/2021" } ] ] } ], "securityTemplateIds": [ "7d6f4e30-f423-11e9-8071-89c0c4052156" ] } }, "CollectionCreateSuccessResponse": { "value": { "message": "{\"collectionId\":\"1daf38b9-5e9e-42e0-b766-c3ff0b198e14\",\"collectionType\":\"secured\",\"asset\":\"{\\\"presignedurls\\\":[{\\\"filename\\\":\\\"collection.png\\\",\\\"filetype\\\":\\\"image/png\\\",\\\"objectId\\\":\\\"1daf38b9-5e9e-42e0-b766-c3ff0b198e14\\\",\\\"fileId\\\":\\\"2c846658-29d6-4809-9462-8f64354e39c0\\\",\\\"originalFileId\\\":\\\"2c846658-29d6-4809-9462-8f64354e39c0\\\",\\\"url\\\":\\\"https://1739271540099-dev-contentstore-tenovos-io.s3-accelerate.amazonaws.com/masters/2c846658-29d6-4809-9462-8f64354e39c0/collection.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=EXAMPLECREDENTIAL%2F20260828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20260828T204229Z&X-Amz-Expires=86400&X-Amz-Security-Token=EXAMPLETOKEN&X-Amz-Signature=EXAMPLESIGNATURE&X-Amz-SignedHeaders=host&x-amz-checksum-crc32=AAAAAA%3D%3D&x-amz-meta-objectid=1daf38b9-5e9e-42e0-b766-c3ff0b198e14&x-amz-sdk-checksum-algorithm=CRC32&x-id=PutObject\\\"}]}\"}", "collectionId": "1daf38b9-5e9e-42e0-b766-c3ff0b198e14", "statusCode": "success" } }, "CollectionCreateErrorResponse": { "value": { "statusCode": "error", "message": "The following fields are required, but are missing [collectionType]" } } }, "parameters": { "id": { "name": "id", "in": "path", "description": "The id parameter can be used to filter response results based on a specific resource in Tenovos, such as the unique id of an Asset, Collection, Story Board, etc. When used to filter event history, only event types and events specifically associated to the resource\nprovided will be returned. This mean event types such as `user.created`, `security.template.created`, etc., will be filtered out any time this parameter is provided.\n\nA 36-character UUID representing the resource.", "schema": { "type": "string", "x-nullable": true, "example": "b84ac1dc-30ed-4741-8f8d-47ef2635950b" } }, "userId": { "name": "userId", "in": "query", "description": "The userId parameter can be used to filter response results based on a specific User in Tenovos. When used to filter event history, only events specifically associated to the User ID\nprovided will be returned.\n\nA 36-character UUID representing the User.", "schema": { "type": "string", "x-nullable": true, "example": "cd0caff5-2756-4d7c-a43d-a926a81fa9b8" } }, "eventType": { "name": "eventType", "in": "query", "description": "The event type parameter can be used to filter response results based on the type of event. For a full list of available types, please refer to the\n[Event Types page](https://api.tenovos.com/developer-portal/webhooks/event-types/) for an up-to-date list of available values.", "schema": { "type": "string", "x-nullable": true, "example": "asset.created" } }, "startDate": { "name": "startDate", "in": "query", "description": "The start of the date range for event history. If not specified, the previous 12 months of events will be returned.\n\nFormat: Full datetime (YYYY-MM-DDTHH:mm:ssZ) for compatibility. \n**Must be URL-encoded if using the full datetime.**", "schema": { "type": "string", "x-nullable": true, "example": "2024-10-12T15:27:59Z" } }, "endDate": { "name": "endDate", "in": "query", "description": "The end of the date range for event history. If not specified, the previous 12 months of events will be returned.\n\nFormat: Full datetime (YYYY-MM-DDTHH:mm:ssZ) for compatibility. \n**Must be URL-encoded if using the full datetime.**", "schema": { "type": "string", "x-nullable": true, "example": "2024-11-09T08:14:56Z" } }, "limit": { "name": "limit", "in": "query", "description": "The limit parameter can be used to limit the response results for each request. When used for event history, the minimum recommended pageSize is `100`. Based on the limiting scope of your \nquery parameters, pageSize can be increased to 1000.", "schema": { "type": "number", "x-nullable": true, "example": 500 } }, "cursor": { "name": "cursor", "in": "query", "description": "Provides the cursor for the next result set. Can be either the response value for `nextCursor` or `prevCursor` depending \non the desired pagination direction.", "schema": { "type": "string", "x-nullable": true, "example": "eyJvZmZzZXQiOjIwMH0" } }, "pull-zone-id": { "name": "pullZoneId", "in": "path", "description": "The pullZoneId parameter can be used to specific the Tenovos CDN Pull Zone that you wish to make requests for.\n\nInt64", "schema": { "type": "integer", "x-nullable": true, "example": 70015645231 } }, "content-type": { "name": "content-type", "in": "header", "schema": { "type": "string", "example": "application/json" } }, "authorization": { "name": "Authorization", "in": "header", "schema": { "type": "string" } }, "api-key": { "name": "X-API-Key", "in": "header", "required": true, "description": "Customer-specific API key required to invoke API.", "schema": { "type": "string" } }, "before": { "name": "before", "in": "query", "description": "The cursor value returned by Tenovos to retrieve the previous page of results. If the before parameter is used, the after parameter cannot be used.", "schema": { "type": "string", "x-nullable": true, "maxLength": 36, "minLength": 12, "example": "196100ac-4ee" } }, "after": { "name": "after", "in": "query", "description": "The cursor value returned by Tenovos to retrieve the next page of results. If the after parameter is used, the before parameter cannot be used.", "schema": { "type": "string", "x-nullable": true, "maxLength": 36, "minLength": 12, "example": "16969100ac-4ef" } }, "subscriptionId": { "name": "id", "in": "path", "required": true, "description": "The Identifier of the subscription, active or not, that you wish to delete.", "schema": { "type": "string", "format": "uuid", "x-nullable": false, "maxLength": 36, "minLength": 36, "example": "4d4d835b-c188-4120-87f9-1208c001e170" } }, "endpointId": { "name": "endpointId", "in": "path", "required": false, "description": "The Id of the endpoint configured for subscription to specified events. Required only for DELETE operations.", "schema": { "type": "string", "x-nullable": false, "example": "ep_2gEymWwsWu5H5EpwbwoOwBnRQBi" } } }, "responses": { "400": { "description": "One or more required parameters are missing or invalid." }, "401": { "description": "Authentication failed (unauthorized)." }, "403": { "description": "Forbidden. You do not have permissions to perform this action, or your connection information is not correct." }, "503": { "description": "The server is too busy to handle the request." } } } }