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
anddescription
) 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-signeduploadUrl
.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'