> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/api-references/readme/api-reference-23/assets.md).

# Assets

Manage Assets

## Retrieving all assets

> Retrieves all assets assigned to the tenant. You can filter, sort, and paginate the results with query parameters.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_read","media.asset_manage","media.asset_read_by_vendor","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"parameters":{"trait_paged_pageNumber":{"name":"pageNumber","in":"query","description":"The page number to be retrieved where the size of the pages must be specified by the `pageSize` parameter. The number of the first page is 1.","schema":{"default":1,"minimum":1,"type":"integer"}},"trait_paged_pageSize":{"name":"pageSize","in":"query","description":"The number of documents being retrieved on the page.\n","schema":{"default":60,"minimum":1,"type":"integer"}},"trait_XTotalCount_header":{"in":"header","name":"X-Total-Count","required":false,"description":"To get information how many entities meet the filtering requirements, the `X-Total-Count` header has been introduced. The header is optional and its default value is `false`. If the header is provided and it is set to `true`, then the total count is returned in the `X-Total-Count` response header. In both cases (X-Total-Count `true`, `false` or not provided), the response body has the same format (array of entities). This means that the information about the total count is returned only on demand, provided that the X-Total-Count header is present in a request.","schema":{"default":false,"type":"boolean"}},"trait_sort":{"in":"query","name":"sort","required":false,"description":"Fields to sort the response data by following the order of the parameters from left to right. Can contain multiple fields in the following format: `field name:sort direction`, separated by a comma. The colon preceding the `sort direction` parameter is optional, and the descending order is taken only if it is equal to `desc` or `DESC`. The ascending order is assumed in any other case.","schema":{"type":"string"}},"query_q_product":{"name":"q","in":"query","description":"A standard query parameter is used to search for specific values.\n\n* Searching for items by string-based properties:\n  * By a field value: `q=access:PUBLIC`, where `access` is the field name, and `PUBLIC` is its desired value.\n* Searching for items by a number-based property:\n  * With a specific value: `q=details.bytes:200`\n  * With a value greater than: `q=details.bytes:>200`\n  * With a value lower than: `q=details.bytes:<200`\n  * With a value greater than or equal to: `q=details.bytes:>=200`\n  * With a value lower than or equal to: `q=details.bytes:<=200`\n  * With a value within a range of values: `q=details.bytes:(>=100 AND <=200)`, where `details.bytes` is the name of a number-based field, and `200` is its querying value.\n* Searching for items by a date-based property: All numer-based property queries are also valid for dates. In that case, the date should be placed within double quotes: `q=metadata.createdAt:(>=\"2021-05-18T07:27:27.455Z\" AND <\"2021-05-20T07:27:27.455Z\")`\n* Searching for items with a nonexistent or empty property: `q=details.filename:null`, where `details.filename` is the field that has its value set to `null`.\n* Searching for items with an existing property: `q=details:exists`, where `details` is the field that has a non-empty value.\n* Searching for items by multiple specific values: `q=id:(5c3325baa9812100098ff48f,5c3325d1a9812100098ff494)`, where `id` is the field name, and strings within the brackets are the desired values.\n* Searching for items by multiple fields: `q=id:5c3325baa9812100098ff48f access:PUBLIC`, where `id` and `access` are field names. All objects that contain the specified values are returned. Multiple fields (separated by spaces) can be specified. Multiple values for each field can also be specified in a format presented earlier.\n* Searching for items with string-based properties conforming to a regex: `q=id:~ABCD12` or `q=id:(~AB CD)` - in the case of searching for strings with a space, where `id` is the name of the field and `ABCD12` or `AB CD` are its querying regular expressions.\n","schema":{"type":"string"}}},"responses":{"GetAssets":{"description":"Resources have been retrieved successfully.","content":{"application/json":{"schema":{"type":"array","description":"List of assets.","items":{"$ref":"#/components/schemas/GetAsset"}}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"GetAsset":{"title":"Get Asset","allOf":[{"$ref":"#/components/schemas/Asset"},{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["BLOB","LINK"],"description":"Asset type. This property is immutable."},"vendorId":{"type":"string","description":"Id of a vendor to which the asset belongs."},"url":{"type":"string","description":"Resource link."},"details":{"$ref":"#/components/schemas/AssetDetailsGet"},"metadata":{"$ref":"#/components/schemas/MetadataGet"}}}]},"Asset":{"title":"Asset","type":"object","properties":{"access":{"type":"string","enum":["PUBLIC","PRIVATE"],"description":"Access type of the asset. This property is immutable. \n- `PUBLIC`: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.\n- `PRIVATE`: Blob assets are stored in Google Cloud Storage. Retrieve their content through `/media/{tenant}/assets/{assetId}/download` or request a temporary signed URL through `/media/{tenant}/assets/{assetId}/download-url`.\n"},"refIds":{"type":"array","description":"List of references.","items":{"$ref":"#/components/schemas/RefId"}},"mixins":{"type":"object","description":"Custom asset attributes."},"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}},"RefId":{"type":"object","properties":{"type":{"type":"string","description":"Reference type. Can be one of the predefined types: `BRAND`, `CATEGORY`, `LABEL`, `PRODUCT`, `MODULE`, `AGENT` or any custom schema type.\n"},"id":{"type":"string","description":"Reference Id."}}},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"A key-value map, where key is a mixin name and value is a link to the mixin schema. Must be provided together with the corresponding mixin values in the `mixins` object."}}},"AssetDetailsGet":{"title":"Asset Response Detailed Information","type":"object","allOf":[{"$ref":"#/components/schemas/AssetDetailsCreate"}],"properties":{"bytes":{"type":"number","description":"Size of the content associated with the asset in bytes."},"etag":{"type":"string","description":"The ETAG digest for the asset."},"md5":{"type":"string","description":"Lowercase hex MD5 of the asset bytes. Empty when the store did not return a content digest."}}},"AssetDetailsCreate":{"title":"Asset Request Detailed Information","type":"object","properties":{"filename":{"type":"string","description":"Asset filename."},"mimeType":{"type":"string","description":"The MIME (media) type of the asset."}}},"MetadataGet":{"type":"object","allOf":[{"$ref":"#/components/schemas/MetadataUpdate"}],"properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."}},"required":["version"]},{"$ref":"#/components/schemas/MetadataCreate"}]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}}},"paths":{"/media/{tenant}/assets":{"get":{"summary":"Retrieving all assets","description":"Retrieves all assets assigned to the tenant. You can filter, sort, and paginate the results with query parameters.","parameters":[{"$ref":"#/components/parameters/trait_paged_pageNumber"},{"$ref":"#/components/parameters/trait_paged_pageSize"},{"$ref":"#/components/parameters/trait_XTotalCount_header"},{"$ref":"#/components/parameters/trait_sort"},{"$ref":"#/components/parameters/query_q_product"}],"responses":{"200":{"$ref":"#/components/responses/GetAssets"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-media-list-assets","tags":["Assets"]}}}}
```

## Creating an asset

> Creates a new asset for the tenant. An asset represents a digital (max 30 MB) object in the system, for example a video, image, or a document.\
> \- To create an asset of the \`BLOB\` type, use the \`multipart/form-data\` request body. \
> \- To create an asset of the \`LINK\` type, use the \`application/json\` request body.\
> \
> \*\*Access and assignment rules:\*\*\
> \- Assets assigned to predefined \`refIds\` types (such as \`CATEGORY\` or \`PRODUCT\`) require \`PUBLIC\` access.\
> \- \`PRIVATE\` access assets can be linked to \`AGENT\`, custom schema types, or remain unassigned.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_manage","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"schemas":{"AssetCreateMultipart":{"title":"Asset Create Multipart Payload","type":"object","properties":{"file":{"type":"object","format":"binary","description":"Content of the file. The max file size is 30 MB."},"body":{"description":"Asset JSON creation payload.","allOf":[{"$ref":"#/components/schemas/AssetCreateBlob"}]}},"required":["file","body"]},"AssetCreateBlob":{"title":"Asset Create Blob Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["BLOB"],"description":"Asset type. This property is immutable."},"details":{"$ref":"#/components/schemas/AssetDetailsCreate"}},"required":["type","access"]},"Asset":{"title":"Asset","type":"object","properties":{"access":{"type":"string","enum":["PUBLIC","PRIVATE"],"description":"Access type of the asset. This property is immutable. \n- `PUBLIC`: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.\n- `PRIVATE`: Blob assets are stored in Google Cloud Storage. Retrieve their content through `/media/{tenant}/assets/{assetId}/download` or request a temporary signed URL through `/media/{tenant}/assets/{assetId}/download-url`.\n"},"refIds":{"type":"array","description":"List of references.","items":{"$ref":"#/components/schemas/RefId"}},"mixins":{"type":"object","description":"Custom asset attributes."},"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}},"RefId":{"type":"object","properties":{"type":{"type":"string","description":"Reference type. Can be one of the predefined types: `BRAND`, `CATEGORY`, `LABEL`, `PRODUCT`, `MODULE`, `AGENT` or any custom schema type.\n"},"id":{"type":"string","description":"Reference Id."}}},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"A key-value map, where key is a mixin name and value is a link to the mixin schema. Must be provided together with the corresponding mixin values in the `mixins` object."}}},"AssetDetailsCreate":{"title":"Asset Request Detailed Information","type":"object","properties":{"filename":{"type":"string","description":"Asset filename."},"mimeType":{"type":"string","description":"The MIME (media) type of the asset."}}},"AssetCreateLink":{"title":"Asset Create Link Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["LINK"],"description":"Asset type. This property is immutable."},"url":{"type":"string","description":"Resource link."}},"required":["type","access","url"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"There are three possible reasons:\n1. Product with given code already exists, please choose unique code for your product\n2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.\n3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"RequestTooLarge_413":{"description":"Media request is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/media/{tenant}/assets":{"post":{"summary":"Creating an asset","description":"Creates a new asset for the tenant. An asset represents a digital (max 30 MB) object in the system, for example a video, image, or a document.\n- To create an asset of the `BLOB` type, use the `multipart/form-data` request body. \n- To create an asset of the `LINK` type, use the `application/json` request body.\n\n**Access and assignment rules:**\n- Assets assigned to predefined `refIds` types (such as `CATEGORY` or `PRODUCT`) require `PUBLIC` access.\n- `PRIVATE` access assets can be linked to `AGENT`, custom schema types, or remain unassigned.","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AssetCreateMultipart"}},"application/json":{"schema":{"$ref":"#/components/schemas/AssetCreateLink"}}}},"responses":{"201":{"description":"The request was successful. The asset has been created.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"409":{"$ref":"#/components/responses/Conflict_409"},"413":{"$ref":"#/components/responses/RequestTooLarge_413"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"POST-media-create-asset","tags":["Assets"]}}}}
```

## Retrieving an asset

> Retrieves an asset by its unique identifier.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_read","media.asset_read_by_vendor","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"responses":{"GetAsset":{"description":"The request was successful. The requested asset is returned.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GetAssetBlob"},{"$ref":"#/components/schemas/GetAssetLink"}]}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"GetAssetBlob":{"title":"Get Asset Blob","type":"object","allOf":[{"$ref":"#/components/schemas/AssetCreateBlob"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"vendorId":{"type":"string","description":"Id of a vendor to which the asset belongs."},"status":{"type":"string","enum":["PENDING","READY"],"description":"Upload state of a `BLOB` created through an upload session.\n* `PENDING` — the session exists and the file is not confirmed yet.\n* `READY` — the file is stored.\nWhen this field is absent, the asset is ready. Assets created by the existing upload endpoints do not return this field.\n"},"details":{"$ref":"#/components/schemas/AssetDetailsGet"},"metadata":{"$ref":"#/components/schemas/MetadataGet"}}},"AssetCreateBlob":{"title":"Asset Create Blob Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["BLOB"],"description":"Asset type. This property is immutable."},"details":{"$ref":"#/components/schemas/AssetDetailsCreate"}},"required":["type","access"]},"Asset":{"title":"Asset","type":"object","properties":{"access":{"type":"string","enum":["PUBLIC","PRIVATE"],"description":"Access type of the asset. This property is immutable. \n- `PUBLIC`: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.\n- `PRIVATE`: Blob assets are stored in Google Cloud Storage. Retrieve their content through `/media/{tenant}/assets/{assetId}/download` or request a temporary signed URL through `/media/{tenant}/assets/{assetId}/download-url`.\n"},"refIds":{"type":"array","description":"List of references.","items":{"$ref":"#/components/schemas/RefId"}},"mixins":{"type":"object","description":"Custom asset attributes."},"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}},"RefId":{"type":"object","properties":{"type":{"type":"string","description":"Reference type. Can be one of the predefined types: `BRAND`, `CATEGORY`, `LABEL`, `PRODUCT`, `MODULE`, `AGENT` or any custom schema type.\n"},"id":{"type":"string","description":"Reference Id."}}},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"A key-value map, where key is a mixin name and value is a link to the mixin schema. Must be provided together with the corresponding mixin values in the `mixins` object."}}},"AssetDetailsCreate":{"title":"Asset Request Detailed Information","type":"object","properties":{"filename":{"type":"string","description":"Asset filename."},"mimeType":{"type":"string","description":"The MIME (media) type of the asset."}}},"AssetDetailsGet":{"title":"Asset Response Detailed Information","type":"object","allOf":[{"$ref":"#/components/schemas/AssetDetailsCreate"}],"properties":{"bytes":{"type":"number","description":"Size of the content associated with the asset in bytes."},"etag":{"type":"string","description":"The ETAG digest for the asset."},"md5":{"type":"string","description":"Lowercase hex MD5 of the asset bytes. Empty when the store did not return a content digest."}}},"MetadataGet":{"type":"object","allOf":[{"$ref":"#/components/schemas/MetadataUpdate"}],"properties":{"createdAt":{"description":"Date and time when the document was created.","type":"string"},"modifiedAt":{"description":"Date and time when the document was last modified.","type":"string"}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."}},"required":["version"]},{"$ref":"#/components/schemas/MetadataCreate"}]},"GetAssetLink":{"title":"Get Asset Link","type":"object","allOf":[{"$ref":"#/components/schemas/AssetCreateLink"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"vendorId":{"type":"string","description":"Id of a vendor to which the asset belongs."},"metadata":{"$ref":"#/components/schemas/MetadataGet"}}},"AssetCreateLink":{"title":"Asset Create Link Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["LINK"],"description":"Asset type. This property is immutable."},"url":{"type":"string","description":"Resource link."}},"required":["type","access","url"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}}},"paths":{"/media/{tenant}/assets/{assetId}":{"get":{"summary":"Retrieving an asset","description":"Retrieves an asset by its unique identifier.","responses":{"200":{"$ref":"#/components/responses/GetAsset"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-media-retrieve-asset","tags":["Assets"]}}}}
```

## Updating an asset

> Updates a given asset. The \`type\` and \`access\` properties are immutable. Accepts files of up to 30 MB.\
> \- To update an asset of the \`BLOB\` type, use \`multipart/form-data\` request body. \
> \- To update an asset of the \`LINK\` type, use \`application/json\` request body.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_manage","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"schemas":{"AssetUpdateMultipart":{"title":"Asset Update Mutlipart Payload","type":"object","properties":{"file":{"type":"object","format":"binary","description":"Content of the file."},"body":{"description":"Asset Json update payload","allOf":[{"$ref":"#/components/schemas/AssetUpdateBlob"}]}},"required":["file","body"]},"AssetUpdateBlob":{"title":"Asset Update Blob Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"type":{"type":"string","enum":["BLOB"],"description":"Asset type. This property is immutable."},"details":{"$ref":"#/components/schemas/AssetDetailsCreate"},"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}},"required":["access","type"]},"Asset":{"title":"Asset","type":"object","properties":{"access":{"type":"string","enum":["PUBLIC","PRIVATE"],"description":"Access type of the asset. This property is immutable. \n- `PUBLIC`: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.\n- `PRIVATE`: Blob assets are stored in Google Cloud Storage. Retrieve their content through `/media/{tenant}/assets/{assetId}/download` or request a temporary signed URL through `/media/{tenant}/assets/{assetId}/download-url`.\n"},"refIds":{"type":"array","description":"List of references.","items":{"$ref":"#/components/schemas/RefId"}},"mixins":{"type":"object","description":"Custom asset attributes."},"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}},"RefId":{"type":"object","properties":{"type":{"type":"string","description":"Reference type. Can be one of the predefined types: `BRAND`, `CATEGORY`, `LABEL`, `PRODUCT`, `MODULE`, `AGENT` or any custom schema type.\n"},"id":{"type":"string","description":"Reference Id."}}},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"A key-value map, where key is a mixin name and value is a link to the mixin schema. Must be provided together with the corresponding mixin values in the `mixins` object."}}},"AssetDetailsCreate":{"title":"Asset Request Detailed Information","type":"object","properties":{"filename":{"type":"string","description":"Asset filename."},"mimeType":{"type":"string","description":"The MIME (media) type of the asset."}}},"MetadataUpdate":{"allOf":[{"type":"object","properties":{"version":{"minimum":1,"type":"integer","description":"Version of the document."}},"required":["version"]},{"$ref":"#/components/schemas/MetadataCreate"}]},"AssetUpdateLink":{"title":"Asset Update Link Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"url":{"type":"string","description":"Resource link."},"type":{"type":"string","enum":["LINK"],"description":"Asset type. This property is immutable."},"metadata":{"$ref":"#/components/schemas/MetadataUpdate"}},"required":["access","url","type"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}},"responses":{"BadRequest_400_Update":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"There are three possible reasons:\n1. Product with given code already exists, please choose unique code for your product\n2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.\n3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"RequestTooLarge_413":{"description":"Media request is too large.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/media/{tenant}/assets/{assetId}":{"put":{"summary":"Updating an asset","description":"Updates a given asset. The `type` and `access` properties are immutable. Accepts files of up to 30 MB.\n- To update an asset of the `BLOB` type, use `multipart/form-data` request body. \n- To update an asset of the `LINK` type, use `application/json` request body.","requestBody":{"content":{"multipart/form-data":{"schema":{"$ref":"#/components/schemas/AssetUpdateMultipart"}},"application/json":{"schema":{"$ref":"#/components/schemas/AssetUpdateLink"}}}},"responses":{"204":{"description":"The asset has been updated successfully."},"400":{"$ref":"#/components/responses/BadRequest_400_Update"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"$ref":"#/components/responses/Conflict_409"},"413":{"$ref":"#/components/responses/RequestTooLarge_413"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"PUT-media-update-asset","tags":["Assets"]}}}}
```

## Deleting an asset

> Deletes an asset.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_manage","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}}},"paths":{"/media/{tenant}/assets/{assetId}":{"delete":{"summary":"Deleting an asset","description":"Deletes an asset.","responses":{"204":{"description":"The asset has been deleted successfully."},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"DELETE-media-remove-asset","tags":["Assets"]}}}}
```

## Partially updating an asset

> Partially updates an asset with a JSON Patch document that follows the \[RFC-6902]\(<https://datatracker.ietf.org/doc/html/rfc6902>) standard.\
> \
> Use this endpoint to change fields such as \`refIds\` without replacing the full asset. You can patch \`BLOB\` assets without re-uploading the file. The \`type\` and \`access\` properties are immutable.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_manage","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"schemas":{"PatchOperation":{"type":"object","properties":{"op":{"type":"string","enum":["add","remove","replace"],"description":"JSON Patch operation. Available operations: `add`, `remove`, and `replace`."},"path":{"type":"string","description":"Path to the field to update.\n\nExamples: `/url`, `/refIds`, `/refIds/-`.\n\nTo append an item to an array, use `add` with a path ending in `/-`. The `-` means append after the last element."},"value":{"description":"Value to add or replace. The value can be a primitive type, an object, or an array."}},"required":["op","path"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}},"responses":{"BadRequest_400_Update":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Conflict_409":{"description":"There are three possible reasons:\n1. Product with given code already exists, please choose unique code for your product\n2. Optimistic locking failed. If user sends metadata/version attribute which is outdated (someone else updated product in the time user was performing his changes). User should retrieve the latest product data and retry the request.\n3. Optimistic locking failed. User did not provide metadata/version attribute in update request, but someone else updated product while it was internally handled by product service. Resending the same request can result in successful update, but the update can override recently persisted changes.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/media/{tenant}/assets/{assetId}":{"patch":{"summary":"Partially updating an asset","description":"Partially updates an asset with a JSON Patch document that follows the [RFC-6902](https://datatracker.ietf.org/doc/html/rfc6902) standard.\n\nUse this endpoint to change fields such as `refIds` without replacing the full asset. You can patch `BLOB` assets without re-uploading the file. The `type` and `access` properties are immutable.","requestBody":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PatchOperation"}}}}},"responses":{"204":{"description":"The asset has been updated successfully."},"400":{"$ref":"#/components/responses/BadRequest_400_Update"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"$ref":"#/components/responses/Conflict_409"},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"PATCH-media-update-asset","tags":["Assets"]}}}}
```

## Downloading an asset

> Downloads an asset by its unique identifier.\
> \
> {% hint style="info" %}\
> \*\*Recommendation:\*\* Use \[Retrieving a download URL]\(<https://developer.emporix.io/api-documentation/api-guides/media/media/api-reference/assets#get-media-tenant-assets-assetid-download-url>) for every download. That call is always faster because the file travels from storage to the client and does not pass through the Media API.\
> {% endhint %}\
> \
> If the asset is \`PENDING\` and its file is not yet available in storage, this endpoint returns \`409\`. If the known value of \`details.bytes\` exceeds the configured streaming limit, it returns \`413\`. The default limit is 31,457,280 bytes (30 MB). Assets without a known byte count are not rejected by this size check. The download URL endpoint has no size limit.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_read","media.asset_read_by_vendor","media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"responses":{"GetPrivateAsset":{"description":"This is a successful response when requesting a PRIVATE BLOB asset.","content":{"text/plain":{"schema":{"type":"string","format":"byte"}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"Version identifier of the resource, necessary for caching."}}},"Redirect":{"description":"This is a successful response when requesting for a PUBLIC access asset.","headers":{"Location":{"schema":{"type":"string"},"description":"Url address of the requested file."}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}},"schemas":{"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}}},"paths":{"/media/{tenant}/assets/{assetId}/download":{"get":{"summary":"Downloading an asset","description":"Downloads an asset by its unique identifier.\n\n{% hint style=\"info\" %}\n**Recommendation:** Use [Retrieving a download URL](https://developer.emporix.io/api-documentation/api-guides/media/media/api-reference/assets#get-media-tenant-assets-assetid-download-url) for every download. That call is always faster because the file travels from storage to the client and does not pass through the Media API.\n{% endhint %}\n\nIf the asset is `PENDING` and its file is not yet available in storage, this endpoint returns `409`. If the known value of `details.bytes` exceeds the configured streaming limit, it returns `413`. The default limit is 31,457,280 bytes (30 MB). Assets without a known byte count are not rejected by this size check. The download URL endpoint has no size limit.","responses":{"200":{"$ref":"#/components/responses/GetPrivateAsset"},"301":{"$ref":"#/components/responses/Redirect"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The upload is not complete because the file is not available in storage yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"413":{"description":"The known file size exceeds the configured streaming download limit, which is 31,457,280 bytes (30 MB) by default.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"operationId":"GET-media-download-asset","tags":["Assets"]}}}}
```

## Starting an upload session

> Starts an upload session for a \`BLOB\` asset and returns a short-lived upload instruction. The file is sent directly to storage. The Media API does not receive the file bytes.\
> \
> {% hint style="info" %}\
> Direct upload is enabled separately for each tenant. Contact \[Emporix Support]\(mailto:<support@emporix.com>) to activate it. If direct upload is not active, the endpoint returns \`403\` with the message \`direct upload is not enabled for this tenant\` and does not create a pending asset.\
> {% endhint %}\
> \
> For a private asset, omit \`uploadType\` or set it to \`put\` to receive a signed Google Cloud Storage \`PUT\` request. Send the file with every returned header. Set \`uploadType\` to \`form\` to receive a Google Cloud Storage multipart \`POST\` policy. For a public asset, the service always returns a Cloudinary multipart \`POST\` form, regardless of \`uploadType\`. For either multipart flow, send every returned field unchanged and append the file part last. Google Cloud Storage form fields do not include \`x-goog-if-generation-match\`.\
> \
> The created asset remains \`PENDING\` until storage confirms the upload, and then becomes \`READY\`. Google Cloud Storage credentials are valid for 15 minutes by default. Cloudinary forms are valid for one hour. The upload session expires after one hour by default. Cleanup removes an expired session when no file is found. If a storage notification is delayed, retrieving the asset or cleanup can detect the stored file and complete the asset. The service emits \`media.asset-created\` only after completion is confirmed. Operations that require the stored file return \`409\` with \`Upload is not complete\` while the file is missing.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_manage"]},{"OAuth2":["media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"schemas":{"UploadSessionRequest":{"title":"Upload Session Request","description":"Payload for creating a direct-storage upload session.","allOf":[{"$ref":"#/components/schemas/AssetCreateBlob"},{"type":"object","properties":{"uploadType":{"type":"string","enum":["put","form"],"default":"put","description":"Upload flow requested for a private Google Cloud Storage asset.\n* `put`: Returns a signed `PUT` request. This is the default when the property is omitted.\n* `form`: Returns a multipart `POST` policy.\nPublic Cloudinary assets always use a multipart `POST` form, regardless of this value.\n"}}}]},"AssetCreateBlob":{"title":"Asset Create Blob Payload","type":"object","allOf":[{"$ref":"#/components/schemas/Asset"}],"properties":{"id":{"type":"string","description":"Unique identifier of an asset."},"type":{"type":"string","enum":["BLOB"],"description":"Asset type. This property is immutable."},"details":{"$ref":"#/components/schemas/AssetDetailsCreate"}},"required":["type","access"]},"Asset":{"title":"Asset","type":"object","properties":{"access":{"type":"string","enum":["PUBLIC","PRIVATE"],"description":"Access type of the asset. This property is immutable. \n- `PUBLIC`: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.\n- `PRIVATE`: Blob assets are stored in Google Cloud Storage. Retrieve their content through `/media/{tenant}/assets/{assetId}/download` or request a temporary signed URL through `/media/{tenant}/assets/{assetId}/download-url`.\n"},"refIds":{"type":"array","description":"List of references.","items":{"$ref":"#/components/schemas/RefId"}},"mixins":{"type":"object","description":"Custom asset attributes."},"metadata":{"$ref":"#/components/schemas/MetadataCreate"}}},"RefId":{"type":"object","properties":{"type":{"type":"string","description":"Reference type. Can be one of the predefined types: `BRAND`, `CATEGORY`, `LABEL`, `PRODUCT`, `MODULE`, `AGENT` or any custom schema type.\n"},"id":{"type":"string","description":"Reference Id."}}},"MetadataCreate":{"type":"object","properties":{"mixins":{"type":"object","additionalProperties":{"type":"string"},"description":"A key-value map, where key is a mixin name and value is a link to the mixin schema. Must be provided together with the corresponding mixin values in the `mixins` object."}}},"AssetDetailsCreate":{"title":"Asset Request Detailed Information","type":"object","properties":{"filename":{"type":"string","description":"Asset filename."},"mimeType":{"type":"string","description":"The MIME (media) type of the asset."}}},"UploadSession":{"title":"Upload Session","type":"object","description":"Instruction for sending a file directly to storage.","properties":{"id":{"type":"string","description":"Unique identifier of the asset, generated when the upload session is created."},"provider":{"type":"string","enum":["GCS","CLOUDINARY"],"description":"Storage that receives the file.\n* `GCS` — private asset. Upload with the returned `PUT` headers or multipart `POST` fields.\n* `CLOUDINARY` — public asset. Upload with `POST` and the returned multipart form fields.\n"},"status":{"type":"string","enum":["PENDING"],"description":"The asset stays `PENDING` until the file is stored."},"expiresAt":{"type":"string","format":"date-time","description":"Date and time when the unused upload session expires. Returned as an ISO-8601 string."},"upload":{"type":"object","description":"The request the caller sends to storage.","properties":{"method":{"type":"string","enum":["PUT","POST"],"description":"HTTP method of the storage request."},"url":{"type":"string","description":"Storage URL that receives the file."},"headers":{"type":"object","additionalProperties":{"type":"string"},"description":"Headers required by a private Google Cloud Storage `PUT` upload. Send every returned header unchanged with the file.\nReturned only for the Google Cloud Storage `PUT` flow.\n"},"fields":{"type":"object","additionalProperties":{"type":"string"},"description":"Fields required by a Google Cloud Storage or Cloudinary multipart `POST`. Send every returned field unchanged, then append the file part last.\nGoogle Cloud Storage fields do not include `x-goog-if-generation-match`. Cloudinary fields include `api_key` and `signature` but never include the API secret.\n"}},"required":["method","url"]}},"required":["id","provider","status","expiresAt","upload"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}},"responses":{"BadRequest_400":{"description":"Request was syntactically incorrect. Details will be provided in the response payload.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/media/{tenant}/assets/upload-session":{"post":{"summary":"Starting an upload session","description":"Starts an upload session for a `BLOB` asset and returns a short-lived upload instruction. The file is sent directly to storage. The Media API does not receive the file bytes.\n\n{% hint style=\"info\" %}\nDirect upload is enabled separately for each tenant. Contact [Emporix Support](mailto:support@emporix.com) to activate it. If direct upload is not active, the endpoint returns `403` with the message `direct upload is not enabled for this tenant` and does not create a pending asset.\n{% endhint %}\n\nFor a private asset, omit `uploadType` or set it to `put` to receive a signed Google Cloud Storage `PUT` request. Send the file with every returned header. Set `uploadType` to `form` to receive a Google Cloud Storage multipart `POST` policy. For a public asset, the service always returns a Cloudinary multipart `POST` form, regardless of `uploadType`. For either multipart flow, send every returned field unchanged and append the file part last. Google Cloud Storage form fields do not include `x-goog-if-generation-match`.\n\nThe created asset remains `PENDING` until storage confirms the upload, and then becomes `READY`. Google Cloud Storage credentials are valid for 15 minutes by default. Cloudinary forms are valid for one hour. The upload session expires after one hour by default. Cleanup removes an expired session when no file is found. If a storage notification is delayed, retrieving the asset or cleanup can detect the stored file and complete the asset. The service emits `media.asset-created` only after completion is confirmed. Operations that require the stored file return `409` with `Upload is not complete` while the file is missing.","operationId":"POST-media-start-upload-session","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSessionRequest"}}}},"responses":{"201":{"description":"The request was successful. The upload session has been created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UploadSession"}}}},"400":{"$ref":"#/components/responses/BadRequest_400"},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"description":"The caller lacks a required management scope, or direct upload is not enabled for the tenant.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Assets"]}}}}
```

## Retrieving a download URL

> Returns a URL for an asset that is already stored.\
> \
> Use this endpoint as the default method for downloading assets. It is always faster than \[Downloading an asset]\(#get-media-tenant-assets-assetid-download) because the file travels from storage to the client and does not pass through the Media API. This operation is not controlled by the direct-upload tenant setting and has no file-size limit.\
> \
> A private \`BLOB\` returns a Google Cloud Storage signed \`GET\`. The URL works without an Emporix access token and expires after 15 minutes by default. A public \`BLOB\` returns its permanent Cloudinary URL, with no expiry. A \`LINK\` asset returns its stored URL.\
> \
> The optional \`disposition\` parameter affects private Google Cloud Storage URLs only. Omit it to use \`attachment\`, or set it to \`inline\`. Public Cloudinary and \`LINK\` URLs remain unchanged. An empty or unsupported value returns \`400\` with \`disposition must be inline or attachment\`.\
> \
> When the asset is still \`PENDING\` and the file is already in storage, this call completes the asset and then returns the URL. When the file is not in storage yet, the call returns \`409\` with \`Upload is not complete\`.

```json
{"openapi":"3.0.0","info":{"title":"Media Service","version":"0.0.1"},"tags":[{"name":"Assets","description":"Manage Assets"}],"servers":[{"url":"https://api.emporix.io"}],"security":[{"OAuth2":["media.asset_read"]},{"OAuth2":["media.asset_read_by_vendor"]},{"OAuth2":["media.asset_manage_by_vendor"]}],"components":{"securitySchemes":{"OAuth2":{"type":"oauth2","flows":{"clientCredentials":{"tokenUrl":"https://api.emporix.io/oauth/token","scopes":{"media.asset_read":"Needed to read assets.","media.asset_manage":"Needed to manage assets.","media.asset_read_by_vendor":"Needed to read assets that belong to the vendor.","media.asset_manage_by_vendor":"Needed to manage assets that belong to the vendor."}}}}},"parameters":{"query_disposition":{"name":"disposition","in":"query","required":false,"description":"Content disposition for a private Google Cloud Storage signed URL. The default is `attachment`.\nThe value does not change public Cloudinary or `LINK` URLs.\n","schema":{"type":"string","enum":["inline","attachment"],"default":"attachment"}}},"schemas":{"DownloadUrl":{"title":"Download URL","type":"object","description":"URL that returns the stored file.","properties":{"provider":{"type":"string","enum":["GCS","CLOUDINARY","LINK"],"description":"Storage that holds the file.\n* `GCS` — private blob. The URL is a signed download and includes `expiresAt`.\n* `CLOUDINARY` — public blob. The URL is permanent.\n* `LINK` — the URL stored on the asset.\n"},"url":{"type":"string","description":"URL of the stored file."},"expiresAt":{"type":"string","format":"date-time","description":"Date and time when a private signed URL stops working. Returned as an ISO-8601 string.\nPresent for `GCS` only.\n"}},"required":["provider","url"]},"errorMessage":{"title":"Error","description":"Schema for specific API errors.","type":"object","properties":{"code":{"type":"integer","description":"HTTP status code.","minimum":100,"maximum":599},"status":{"description":"HTTP status.","type":"string"},"message":{"description":"Descriptive error message for debugging.","type":"string"},"details":{"description":"List of problems causing this error.","type":"array","items":{"title":"Error Detail","description":"Error details.","type":"string"}},"resourceId":{"description":"Id of the resource.","type":"string"}},"required":["status","code","message"]}},"responses":{"Unauthorized_401":{"description":"Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.","content":{"application/json":{"schema":{"type":"object","properties":{"fault":{"type":"object","properties":{"faultstring":{"type":"string"},"detail":{"type":"object","properties":{"errorcode":{"type":"string"}}}}}}}}}},"Forbidden_403":{"description":"Given authorization scopes are not sufficient and do not match scopes required by the endpoint.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"NotFound_404":{"description":"The requested resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"InternalServiceError_500":{"description":"Internal Service Error occurred.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}}}},"paths":{"/media/{tenant}/assets/{assetId}/download-url":{"get":{"summary":"Retrieving a download URL","description":"Returns a URL for an asset that is already stored.\n\nUse this endpoint as the default method for downloading assets. It is always faster than [Downloading an asset](#get-media-tenant-assets-assetid-download) because the file travels from storage to the client and does not pass through the Media API. This operation is not controlled by the direct-upload tenant setting and has no file-size limit.\n\nA private `BLOB` returns a Google Cloud Storage signed `GET`. The URL works without an Emporix access token and expires after 15 minutes by default. A public `BLOB` returns its permanent Cloudinary URL, with no expiry. A `LINK` asset returns its stored URL.\n\nThe optional `disposition` parameter affects private Google Cloud Storage URLs only. Omit it to use `attachment`, or set it to `inline`. Public Cloudinary and `LINK` URLs remain unchanged. An empty or unsupported value returns `400` with `disposition must be inline or attachment`.\n\nWhen the asset is still `PENDING` and the file is already in storage, this call completes the asset and then returns the URL. When the file is not in storage yet, the call returns `409` with `Upload is not complete`.","operationId":"GET-media-retrieve-download-url","parameters":[{"$ref":"#/components/parameters/query_disposition"}],"responses":{"200":{"description":"The request was successful. The download URL is returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadUrl"}}}},"400":{"description":"The disposition value is empty or unsupported.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"401":{"$ref":"#/components/responses/Unauthorized_401"},"403":{"$ref":"#/components/responses/Forbidden_403"},"404":{"$ref":"#/components/responses/NotFound_404"},"409":{"description":"The upload is not complete. The file is not in storage yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorMessage"}}}},"500":{"$ref":"#/components/responses/InternalServiceError_500"}},"tags":["Assets"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developer.emporix.io/api-references/readme/api-reference-23/assets.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
