CommunitySupport PortalYouTubeFree trialSign Up!

Assets

Manage Assets

Retrieving all assets

get

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

Required scopes

  • media.asset_read

  • media.asset_read_by_vendor - allows to read assets which belong to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
Query parameters
pageNumberinteger · min: 1Optional

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.

Default: 1
pageSizeinteger · min: 1Optional

The number of documents being retrieved on the page.

Default: 60
sortstringOptional

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: name,metadata.createdAt:desc
qstringOptional

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: name:{name}
Header parameters
X-Total-CountbooleanOptional

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.

Default: false
Responses
200

Resources have been retrieved successfully.

application/json
get
/media/{tenant}/assets
GET /media/{tenant}/assets HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

[
  {
    "id": "123e06ecf0452c2d6c0b81390",
    "type": "BLOB",
    "access": "PUBLIC",
    "url": "https://api.emporix/tenant/id/download",
    "details": {
      "filename": "public.txt",
      "mimeType": "text/plain"
    },
    "refIds": [
      {
        "id": "123e06ecf0452c2d6c0b81392",
        "type": "CATEGORY"
      }
    ],
    "metadata": {
      "createdAt": "2022-03-31T13:18:02.379Z",
      "modifiedAt": "2022-03-31T13:18:02.379Z",
      "version": 1
    }
  },
  {
    "id": "123e06ecf0452c2d6c0b81390",
    "type": "LINK",
    "access": "PUBLIC",
    "url": "https://emporix.io/docs/index.html",
    "metadata": {
      "createdAt": "2022-03-31T13:18:02.379Z",
      "modifiedAt": "2022-03-31T13:18:02.379Z",
      "version": 1
    },
    "refIds": [
      {
        "id": "123e06ecf0452c2d6c0b81392",
        "type": "CATEGORY"
      }
    ]
  }
]

Creating an asset

post

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

  • media.asset_manage_by_vendor - allows to create an asset for products which belong to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
Body
fileobject · binaryRequired

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

bodyall ofRequired

Asset Json creation payload

Responses
201

The request was successful. The asset has been created.

application/json
post
/media/{tenant}/assets
POST /media/{tenant}/assets HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 317

{
  "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"
    }
  }
}
{
  "id": "53ac81fd0cce8b26b36f3492"
}

Retrieving an asset

get

Retrieves an asset by its unique identifier.

Required scopes

  • media.asset_read

  • media.asset_read_by_vendor - allows to read an asset which belongs to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
assetIdstringRequired

Unique identifier of an asset.

Responses
200

The request was successful. The requested asset is returned.

application/json
Responseone of
or
get
/media/{tenant}/assets/{assetId}
GET /media/{tenant}/assets/{assetId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "id": "123e06ecf0452c2d6c0b81390",
  "type": "LINK",
  "access": "PUBLIC",
  "url": "https://emporix.io/docs/index.html",
  "refIds": [
    {
      "id": "123e06ecf0452c2d6c0b81392",
      "type": "CATEGORY"
    }
  ],
  "metadata": {
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z",
    "version": 1
  }
}

Updating an asset

put

Updates a given asset. The type and access properties are immutable. Accepts files of up to 10MB.

  • 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

  • media.asset_manage_by_vendor - allows to update an asset which belong to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
assetIdstringRequired

Unique identifier of an asset.

Body
fileobject · binaryRequired

Content of the file.

bodyall ofRequired

Asset Json update payload

Responses
204

The asset has been updated successfully.

No content
put
/media/{tenant}/assets/{assetId}
PUT /media/{tenant}/assets/{assetId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 342

{
  "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
    }
  }
}
No content

Deleting an asset

delete

Deletes an asset.

Required scopes

  • media.asset_manage

  • media.asset_manage_by_vendor - allows to delete an asset which belong to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
assetIdstringRequired

Unique identifier of an asset.

Responses
204

The asset has been deleted successfully.

No content
delete
/media/{tenant}/assets/{assetId}
DELETE /media/{tenant}/assets/{assetId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

No content

Downloading an asset

get

Downloads an asset by its unique identifier.

Required scopes

  • media.asset_read

  • media.asset_read_by_vendor - allows to download an asset which belongs to the vendor

Authorizations
Path parameters
tenantstring · min: 3 · max: 16Required

The tenant that the caller is acting upon.

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

Pattern: ^[a-z][a-z0-9]+$
assetIdstringRequired

Unique identifier of an asset.

Responses
200

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

text/plain
Responsestring · byte
get
/media/{tenant}/assets/{assetId}/download
GET /media/{tenant}/assets/{assetId}/download HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

Ynl0ZXM=
PreviousMediaNextModels

Was this helpful?