Ctrlk
CommunitySupport PortalYouTubeFree trialSign Up!
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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
This endpoint requires the following scopes:
  • : Needed to read assets.
  • : Needed to manage assets.
  • : Needed to read assets that belong to the vendor.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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
accessstring · enumOptional

Access type of the asset. This property is immutable.

  • PUBLIC: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.
  • 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.
Possible values:
mixinsobjectOptional

Custom asset attributes.

idstringOptional

Unique identifier of an asset.

typestring · enumOptional

Asset type. This property is immutable.

Possible values:
vendorIdstringOptional

Id of a vendor to which the asset belongs.

urlstringOptional

Resource link.

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"
      }
    ],
    "mixins": {
      "mediaCustomAttributes": {
        "altText": "Cordless impact driver"
      }
    },
    "metadata": {
      "createdAt": "2022-03-31T13:18:02.379Z",
      "modifiedAt": "2022-03-31T13:18:02.379Z",
      "version": 1,
      "mixins": {
        "mediaCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/mediaCustomAttributesMixIn-v1.json"
      }
    }
  },
  {
    "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 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.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage assets.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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 30 MB.

Responses
201

The request was successful. The asset has been created.

application/json
idstringOptional
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: 533

{
  "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"
    },
    "mixins": {
      "mediaCustomAttributes": {
        "altText": "Cordless impact driver"
      }
    },
    "metadata": {
      "mixins": {
        "mediaCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/mediaCustomAttributesMixIn-v1.json"
      }
    }
  }
}
{
  "id": "53ac81fd0cce8b26b36f3492"
}

Retrieving an asset

get

Retrieves an asset by its unique identifier.

Required scopes
This endpoint requires the following scopes:
  • : Needed to read assets.
  • : Needed to read assets that belong to the vendor.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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
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"
    }
  ],
  "mixins": {
    "mediaCustomAttributes": {
      "altText": "Product specification sheet"
    }
  },
  "metadata": {
    "createdAt": "2022-03-31T13:18:02.379Z",
    "modifiedAt": "2022-03-31T13:18:02.379Z",
    "version": 1,
    "mixins": {
      "mediaCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/mediaCustomAttributesMixIn-v1.json"
    }
  }
}

Updating an asset

put

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.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage assets.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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.

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: 545

{
  "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"
    },
    "mixins": {
      "mediaCustomAttributes": {
        "altText": "Cordless impact driver"
      }
    },
    "metadata": {
      "version": 1,
      "mixins": {
        "mediaCustomAttributes": "https://res.cloudinary.com/saas-ag/raw/upload/emporix-docs/mediaCustomAttributesMixIn-v1.json"
      }
    }
  }
}
No content

Deleting an asset

delete

Deletes an asset.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage assets.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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

Partially updating an asset

patch

Partially updates an asset with a JSON Patch document that follows the RFC-6902 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.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage assets.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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.

Bodyobject · PatchOperation[]
opstring · enumRequired

JSON Patch operation. Available operations: add, remove, and replace.

Possible values:
pathstringRequired

Path to the field to update.

Examples: /url, /refIds, /refIds/-.

To append an item to an array, use add with a path ending in /-. The - means append after the last element.

valueanyOptional

Value to add or replace. The value can be a primitive type, an object, or an array.

Responses
204

The asset has been updated successfully.

No content
patch/media/{tenant}/assets/{assetId}
PATCH /media/{tenant}/assets/{assetId} HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 76

[
  {
    "op": "add",
    "path": "/refIds/-",
    "value": {
      "id": "product1",
      "type": "PRODUCT"
    }
  }
]
No content

Downloading an asset

get

Downloads an asset by its unique identifier.

Recommendation: Use Retrieving a 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.

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.

Required scopes
This endpoint requires the following scopes:
  • : Needed to read assets.
  • : Needed to read assets that belong to the vendor.
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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 a PRIVATE BLOB asset.

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=

Starting an upload session

post

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.

Direct upload is enabled separately for each tenant. Contact Emporix Support 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.

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.

Required scopes
This endpoint requires the following scopes:
  • : Needed to manage assets.
or
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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
accessstring · enumRequired

Access type of the asset. This property is immutable.

  • PUBLIC: Blob assets are stored in Cloudinary and are accessible through a permanent external URL.
  • 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.
Possible values:
mixinsobjectOptional

Custom asset attributes.

idstringOptional

Unique identifier of an asset.

typestring · enumRequired

Asset type. This property is immutable.

Possible values:
uploadTypestring · enumOptional

Upload flow requested for a private Google Cloud Storage asset.

  • put: Returns a signed PUT request. This is the default when the property is omitted.
  • form: Returns a multipart POST policy. Public Cloudinary assets always use a multipart POST form, regardless of this value.
Default: putPossible values:
Responses
201

The request was successful. The upload session has been created.

application/json

Instruction for sending a file directly to storage.

idstringRequired

Unique identifier of the asset, generated when the upload session is created.

providerstring · enumRequired

Storage that receives the file.

  • GCS — private asset. Upload with the returned PUT headers or multipart POST fields.
  • CLOUDINARY — public asset. Upload with POST and the returned multipart form fields.
Possible values:
statusstring · enumRequired

The asset stays PENDING until the file is stored.

Possible values:
expiresAtstring · date-timeRequired

Date and time when the unused upload session expires. Returned as an ISO-8601 string.

post/media/{tenant}/assets/upload-session
POST /media/{tenant}/assets/upload-session HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 130

{
  "type": "BLOB",
  "access": "PRIVATE",
  "uploadType": "put",
  "details": {
    "filename": "installation-guide.pdf",
    "mimeType": "application/pdf"
  }
}
{
  "id": "68d67e9a3f7c2b1e4a8d6501",
  "provider": "GCS",
  "status": "PENDING",
  "expiresAt": "2026-09-25T14:15:00Z",
  "upload": {
    "method": "PUT",
    "url": "https://storage.googleapis.com/{{GCS_BUCKET}}/{{tenant}}/assets/68d67e9a3f7c2b1e4a8d6501?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=%5Bredacted%5D&X-Goog-Date=20260925T131500Z&X-Goog-Expires=900&X-Goog-SignedHeaders=content-type%3Bhost%3Bx-goog-meta-emporix-upload&ifGenerationMatch=0&X-Goog-Signature=%5Bredacted%5D",
    "headers": {
      "Content-Type": "application/pdf",
      "x-goog-meta-emporix-upload": "session"
    }
  }
}

Retrieving a download URL

get

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

Required scopes
This endpoint requires the following scopes:
  • : Needed to read assets.
or
  • : Needed to read assets that belong to the vendor.
or
  • : Needed to manage assets that belong to the vendor.
Authorizations
OAuth2clientCredentialsRequired
Token URL:
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.

Query parameters
dispositionstring · enumOptional

Content disposition for a private Google Cloud Storage signed URL. The default is attachment. The value does not change public Cloudinary or LINK URLs.

Default: attachmentPossible values:
Responses
200

The request was successful. The download URL is returned.

application/json

URL that returns the stored file.

providerstring · enumRequired

Storage that holds the file.

  • GCS — private blob. The URL is a signed download and includes expiresAt.
  • CLOUDINARY — public blob. The URL is permanent.
  • LINK — the URL stored on the asset.
Possible values:
urlstringRequired

URL of the stored file.

expiresAtstring · date-timeOptional

Date and time when a private signed URL stops working. Returned as an ISO-8601 string. Present for GCS only.

get/media/{tenant}/assets/{assetId}/download-url
GET /media/{tenant}/assets/{assetId}/download-url HTTP/1.1
Host: api.emporix.io
Authorization: Bearer YOUR_OAUTH2_TOKEN
Accept: */*

{
  "provider": "GCS",
  "url": "https://storage.googleapis.com/{{GCS_BUCKET}}/{{tenant}}/assets/68d67e9a3f7c2b1e4a8d6501?X-Goog-Algorithm=GOOG4-RSA-SHA256&X-Goog-Credential=%5Bredacted%5D&X-Goog-Date=20260925T133000Z&X-Goog-Expires=900&X-Goog-SignedHeaders=host&response-content-disposition=attachment%3B%20filename%3D%22installation-guide.pdf%22&response-content-type=application%2Fpdf&X-Goog-Signature=%5Bredacted%5D",
  "expiresAt": "2026-09-25T13:45:00Z"
}
PreviousMedia
NextModels

Last updated

Was this helpful?