Skip to main content

Asset Management

This guide aims to clarify the most frequently used calls when it comes to asset management through examples. The following sections will explain how you can manage the assets in the content library and its metadata (permissions, authors, locale properties, tags, etc.).

Retrieving Existing Assets​

Getting asset objects can be done by doing GET request to https://{subdomain}.api.showpad.com/v4/assets/{assetId} (where {assetId} is the ID of the asset) or https://{subdomain}.api.showpad.com/v4/assets will return a single asset or a list of assets, respectively.

See sample requests below:

# Getting a single asset
curl --request GET \
  --url https://customer.api.showpad.com/v4/assets/cc55b0cf8eef46f71d3a6398734e0611 \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'
# Getting a list of assets
curl --request GET \
  --url https://customer.api.showpad.com/v4/assets \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'

Check out the API Specification for more information regarding the API.

Creating New Assets​

Creating a new asset is done by doing a POST request to https://{subdomain}.api.showpad.com/v4/assets.

See the sample request below:

curl --request POST \
  --url https://customer.api.showpad.com/v4/assets \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "My Document.pdf",
    "division": {
      "id": "f541710283954a89bdfd40f221882451"
    },
    "externalId": "my-custom-id",
    "description": "string"
  }'
note

  • External ID: The externalId is an optional attribute used when creating an asset. This attribute is useful to track assets that exist in another platform.

  • The newly created asset will be in the prepared state. The asset, by default, is not visible in the Showpad library; a binary file must be uploaded first. To upload the binary file, please refer to the section below.

  • The request body above only shows the required fields and some optional ones (i.e., externalId and description) for this request. For a full overview of all data that can be passed on in the request body, please refer to the API Specification.

Creating Asset Files​

To create an asset file within an asset, make a POST request to https://{subdomain}.api.showpad.com/v4/assets/{assetId}/files where {assetId} is the ID of an asset that needs to be updated.

This request is used in two (2) scenarios:

  • Uploading a binary file for the new asset that was created via the /v4/assets endpoint. Once the uploaded binary file is processed, the new asset will be visible in the content library.
  • Uploading a new version of an existing asset in Showpad.

See the sample request below:

curl --request POST \
  --url https://customer.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65/files \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "video.mp4"
  }'

The response will be something like below:

{
  "uploadMeta": {
    "uploadUrl": "https://s3.amazonaws.com/path/to/bucket/with/signed/credentials",
    "suggestedContentType": "video/mp4"
  },
  "createdAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
important

The uploadMeta property in the response will contain a self-signed uploadUrl and suggestedContentType. The binary contents of the file needs to be uploaded via a PUT request towards the uploadUrl, with the HTTP header Content-Type set to the value of suggestedContentType. Based on the response above, this should be the request:

curl --request PUT \
  --url https://s3.amazonaws.com/path/to/bucket/with/signed/credentials \
  --header 'Content-Type: video/mp4'

In summary, to create a new asset and make it available in Showpad's content library, you will need to make three (3) requests:

  • POST /v4/assets will generate an asset ID for the new asset.
  • POST /v4/assets/{assetID}/files will return a pre-signed uploadUrl.
  • PUT {uploadUrl} will upload the binary file to the Showpad servers.

Updating Asset Metadata​

To update existing metadata of an asset, make a POST request to https://{subdomain}.api.showpad.com/v4/assets/{assetId} where {assetId} is the ID on an asset that needs updating. While this updates some basic asset metadata, it also supports permissions changes, tags management, and management of locale properties.

See the sample request below:

curl --request POST \
  --url https://customer.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65 \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "my-asset.png",
    "externalId": "my-custom-id",
    "description": "string",
    "permissions": {
      "isAnnotatable": true,
      "isEditable": true,
      "isShareable": true
    },
    "isProcessedUsed": true,
    "isDivisionShared": false,
    "isSensitive": false,
    "isArchived": false,
    "isRenderExternalAllowed": true,
    "isOnlyEntireDocumentShareable": true,
    "lockedPages": [
      {
        "start": 0,
        "end": 0
      }
    ],
    "expiresAt": "2019-08-24T14:15:22Z",
    "releasedAt": "2019-08-24T14:15:22Z",
    "url": "string",
    "tags": [
      {
        "id": "df391e1da6ed4db8a8085838f7abd130"
      }
    ],
    "languages": [
      {
        "code": "en"
      }
    ],
    "countries": [
      {
        "code": "US"
      }
    ],
    "authors": [
      {
        "id": "83a5a807b3c487c91f39d1c3da00b5d6"
      }
    ],
    "downloadableExternal": [
      "original"
    ],
    "downloadableInternal": [
      "original"
    ]
  }'
note

For a full overview of all data that can be passed on in the request body, please refer to the API Specification.

Deleting Assets​

warning

This endpoint will permanently delete an asset from Showpad.

Deleting an asset is as simple as making a DELETE request to https://{subdomain}.api.showpad.com/v4/assets/{assetId} endpoint, where {assetId} is the Asset ID of the asset object to be deleted.

See the sample request below:

curl --request DELETE \
  --url https://customer.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65 \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'