Media Service

Download OpenAPI specification:Download

E-mail: documentation@emporix.com

The Media Service allows you to manage assets associated with your tenant. The assets may include media, such as images or video, and other files, for example contracts or specification sheets.

Assets

Manage Assets

Creating an asset

Creates a new asset for the tenant. An asset represents a digital (max 50MB) 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.

Required scopes

  • media.asset_manage
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

The tenant that the caller is acting upon.

Note: The tenant name should always be written in lowercase.

Request Body schema:
file
required
object <binary>

Content of the file. The max file size is 10MB.

required
object (Asset Create Blob Payload)

Asset Json creation payload

Responses
201

The request was successful. The asset has been created.

400

Request was syntactically incorrect. Details will be provided in the response payload.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

409

There are three possible reasons:

  1. Product with given code already exists, please choose unique code for your product
  2. 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.
  3. 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.
413

Media request is too large.

500

Internal Service Error occurred.

post/{tenant}/assets
Request samples 
{
  "file": {
    "externalValue": "https://res.cloudinary.com/saas-ag/image/upload/v1695804155/emporix-logo-white-2f5e621206edefea6015fb4793959376_nswfbz.png"
  },
  "body": {
    "type": "BLOB",
    "access": "PUBLIC",
    "refIds": [
      {
        "id": "123e06ecf0452c2d6c0b81392",
        "type": "CATEGORY"
      }
    ],
    "details": {
      "filename": "theBestImage",
      "mimeType": "image/jpg"
    }
  }
}
Response samples
application/json
{
  • "id": "53ac81fd0cce8b26b36f3492"
}

Retrieving all assets

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

Required scopes

  • media.asset_read
SecurityOAuth2
Request
path Parameters
tenant
required
string [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$

The tenant that the caller is acting upon.

Note: The tenant name should always be written in lowercase.

query Parameters
pageNumber
integer >= 1
Default: 1

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.

pageSize
integer >= 1
Default: 60

The number of documents being retrieved on the page.

sort
string

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.

Example: sort=name,metadata.createdAt:desc
q
string

A standard query parameter is used to search for specific values.

  • Searching for items by string-based properties:
    • By a field value: q=access:PUBLIC, where access is the field name, and PUBLIC is its desired value.
  • Searching for items by a number-based property:
    • With a specific value: q=details.bytes:200
    • With a value greater than: q=details.bytes:>200
    • With a value lower than: q=details.bytes:<200
    • With a value greater than or equal to: q=details.bytes:>=200
    • With a value lower than or equal to: q=details.bytes:<=200
    • 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.
  • 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")
  • 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.
  • Searching for items with an existing property: q=details:exists, where details is the field that has a non-empty value.
  • 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.
  • 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.
  • 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.
Example: q=name:{name}
header Parameters
X-Total-Count
boolean
Default: false

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.

Responses
200

Resources have been retrieved successfully.

401

Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.

403

Given authorization scopes are not sufficient and do not match scopes required by the endpoint.

500

Internal Service Error occurred.

get/{tenant}/assets
Request samples 
Response samples 
application/json
[
  • {
    },
  • {
    }
]
Retrieving an asset
Retrieves an asset by its unique identifier.




Required scopes


    

  • media.asset_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: The tenant name should always be written in lowercase.


 
assetId
required
string
Unique identifier of an asset.


 
Responses 
200
The request was successful. The requested asset is returned.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource does not exist.


500
Internal Service Error occurred.


get/{tenant}/assets/{assetId}
Request samples 
Response samples 
application/json
{
  • "id": "123e06ecf0452c2d6c0b81390",
  • "type": "LINK",
  • "access": "PUBLIC",
  • "url": "https://emporix.io/docs/index.html",
  • "refIds": [
    ],
  • "metadata": {
    }
}
Updating an asset
Updates a given asset. The type and access properties are immutable. Accepts files of up to 50MB.


    

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





Required scopes


    

  • media.asset_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: The tenant name should always be written in lowercase.


 
assetId
required
string
Unique identifier of an asset.


 
Request Body schema: 
file
required
object <binary> 
Content of the file.


 
required
object (Asset Update Blob Payload) 
Asset Json update payload


 
Responses 
204
The asset has been updated successfully.


400
Request was syntactically incorrect. Details will be provided in the response payload.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource does not exist.


409
There are three possible reasons:


    

  1. Product with given code already exists, please choose unique code for your product
    2. 

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

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



413
Media request is too large.


500
Internal Service Error occurred.


put/{tenant}/assets/{assetId}
Request samples 
{
  "file": {
    "externalValue": "https://res.cloudinary.com/saas-ag/image/upload/v1695804155/emporix-logo-white-2f5e621206edefea6015fb4793959376_nswfbz.png"
  },
  "body": {
    "type": "BLOB",
    "access": "PUBLIC",
    "refIds": [
      {
        "id": "123e06ecf0452c2d6c0b81392",
        "type": "CATEGORY"
      }
    ],
    "details": {
      "filename": "theBestImage",
      "mimeType": "image/jpg"
    },
    "metadata": {
      "version": 1
    }
  }
}
Response samples 
application/json
{}
Deleting an asset
Deletes an asset.


Required scopes


    

  • media.asset_manage
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: The tenant name should always be written in lowercase.


 
assetId
required
string
Unique identifier of an asset.


 
Responses 
204
The asset has been deleted successfully.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


500
Internal Service Error occurred.


delete/{tenant}/assets/{assetId}
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}
Downloading an asset
Downloads an asset by its unique identifier.




Required scopes


    

  • media.asset_read
    • 



SecurityOAuth2 
Request 
path Parameters
tenant
required
string  [ 3 .. 16 ] characters ^[a-z][a-z0-9]+$
The tenant that the caller is acting upon.


Note: The tenant name should always be written in lowercase.


 
assetId
required
string
Unique identifier of an asset.


 
Responses 
200
This is a successful response when requesting for a PRIVATE access asset of the BLOB type.


301
This is a successful response when requesting for a PUBLIC access asset.


401
Given request is unauthorized - the authorization token is invalid or has expired. Details will be provided in the response payload.


403
Given authorization scopes are not sufficient and do not match scopes required by the endpoint.


404
The requested resource does not exist.


500
Internal Service Error occurred.


get/{tenant}/assets/{assetId}/download
Request samples 
Response samples 
application/json
{
  • "fault": {
    }
}