Assets Server REST API - Create asset

What does it do?

Creates assets. Uploads and downloads originals, previews, and thumbnails.

Log in requirement

All calls require an authenticated session, as described in Assets Server REST API - login.

Create Asset API

Creates an asset 'placeholder': the asset record with its metadata. The file itself is uploaded afterwards to the returned uploadUrl.

Parameters

Result

Examples

Request

curl -X POST "https://yourserver.com/api/asset" \
  -H "Authorization: Bearer <authToken>" \
  -H "Content-Type: application/json" \
  -d '{
    "assetPath": "/Demo Zone/Images/my-photo.jpg",
    "autoRename": true,
    "metadata": {
      "description": "My uploaded photo"
    },
    "metadataToReturn": ["filename", "assetPath"]
  }'

Response

{
  "id": "EXc_g0Bw4W7BPZy0h8BFOG",
  "metadata": {
    "id": "EXc_g0Bw4W7BPZy0h8BFOG",
    "filename": "my-photo.jpg",
    "assetPath": "/Demo Zone/Images/my-photo.jpg"
  },
  "permissions": "VPWUMERXCGD",
  "thumbnailUrl": null,
  "previewUrl": null,
  "originalUrl": null,
  "uploadUrl": "https://assets.example.com/api/asset/EXc_g0Bw4W7BPZy0h8BFOG/original?createVersion=false&requestSecret=eyJhbGciOiJIUzI1NiJ9..."
}

Uploading files

Step 1. Create the asset using the Create asset API as described above.

Step 2. Send the file data to the uploadUrl. The HTTP method determines how the file data is handled:

Note: The uploadUrl is valid for 4 hours.

Upload original API - streaming upload

Uploads a file for an asset placeholder or replaces an existing asset's original.

The data is streamed; it is not buffered in memory first.

Parameters

Result

The updated asset object:

Example

curl -X PUT "https://assets.example.com/api/asset/EXc_g0Bw4W7BPZy0h8BFOG/original?createVersion=false&requestSecret=eyJhbGciOiJIUzI1NiJ9..." \
  -H "Content-Type: application/octet-stream" \
  -H "Content-Length: 123456" \
  --upload-file /path/to/my-photo.jpg

Upload original API - multipart upload

Uploads a file for an asset placeholder or replaces an existing asset's original.

The complete file is buffered by the server before it is stored.

Note: For large files, the streaming upload is preferred..

Parameters

Result

Same as for the Streaming upload API.

Example

curl -X POST "https://assets.example.com/api/asset/EXc_g0Bw4W7BPZy0h8BFOG/original" \
  -H "Authorization: Bearer <authToken>" \
  -F "file=@/path/to/my-photo.jpg"

Get asset API

Returns the asset with the matching ID.

Parameters

Result

Search assets API

Searches for assets.

The query uses the same syntax as the Search API.

Parameters

Result

Examples

Request

curl "https://yourserver.com/api/asset/search?q=filename:my-photo.jpg&size=5" \
  -H "Authorization: Bearer <authToken>"

Response

{
  "total": 1,
  "hits": [
    {
      "id": "EXc_g0Bw4W7BPZy0h8BFOG",
      "thumbnailUrl": "https://yourserver.com/thumbnail/EXc_g0Bw4W7BPZy0h8BFOG/...",
      "previewUrl": "https://yourserver.com/preview/EXc_g0Bw4W7BPZy0h8BFOG/...",
      "originalUrl": "https://yourserver.com/file/EXc_g0Bw4W7BPZy0h8BFOG/my-photo.jpg",
      "highlightedText": null,
      "metadata": {
        "filename": "my-photo.jpg",
        "assetPath": "/Demo Zone/Images/my-photo.jpg",
        "extension": "jpg",
        "mimeType": "image/jpeg"
      }
    }
  ]
}

Download APIs

Downloads the asset's original file, thumbnail or preview.

Note: When the thumbnail or preview has not been generated yet, it is generated on the fly.

Parameters

Signed URL APIs

Returns time-limited signed URLs for the originals, previews or thumbnails of the given assets.

A signed URL can be used to download the file without further authentication.

Parameters

Result

An array of objects:

Example

curl "https://yourserver.com/api/asset/EXc_g0Bw4W7BPZy0h8BFOG,6He5UybK4EV8F0sfuAga_X/signed-original-url?validFor=3600" \
  -H "Authorization: Bearer <authToken>"

[
  {
    "assetId": "EXc_g0Bw4W7BPZy0h8BFOG",
    "signedUrl": "https://assets.example.com/file/EXc_g0Bw4W7BPZy0h8BFOG/*/my-photo.jpg?requestSecret=eyJhbGciOiJIUzI1NiJ9..."
  }
]

Signed image rendition URL API

Returns time-limited signed URLs for image renditions that are generated from the originals of the given assets with the requested settings.

Parameters

Result

Same as for the Signed URL API.

Permissions

The permissions field returned by several APIs is a string in which every position represents a permission of the current user on the asset.

A permission that is not granted is shown as -.