Asset Management

The following sections explain how you can manage your assets and their metadata (permissions, authors, locale properties, tags, etc.) in your Showpad content Library.

Base Endpoint

The base endpoint for asset management calls is:

https://{{subdomain}}.api.showpad.com

Every request needs to be prefixed with the base endpoint.

Create Assets

To create a new asset and make it available in Showpad's content library, you need to make three requests:

	Method	Endpoint	Description
1.	POST	/v4/assets	Generates an asset ID for the new asset.
2.	POST	/v4/assets/{assetID}/files	Preparation for binary file. Returns a response with a: pre-signed uploadUrl suggestedContentType
3.	PUT	{uploadUrl}	To upload the binary file to the Showpad servers. Once the uploaded binary file is processed, the new asset will be visible in the content library.

1. Asset ID

The first step in creating a new asset is to create a placeholder with an identifier (ID). This is done via a POST request to https://{{subdomain}}.api.showpad.com/v4/assets.

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, refer to the next step.

Example Request

curl --request POST \
  --url https://{{subdomain}}.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"
  }'

This example only shows required fields and some optional ones (e.g., externalId and description). For an overview of all data that can be passed in the request body, please refer to the API Specification.

2. Asset File

The next step is to create a placeholder for an asset file with the asset ID via a POST request to https://{{subdomain}}.api.showpad.com/v4/assets/{assetId}/files. Be sure to replace {assetId} with the ID of your asset.

This request can be used in two scenarios, uploading a:

• binary file for a new asset.
• new version of an existing asset.

Example Request

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

Example Response

The response provides an uploadMeta property that contains a self-signed uploadUrl and suggestedContentType.

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

3. Upload Binary

The final step is a PUT request to upload the binary contents of the asset file to the uploadUrl.

The Content-Type HTTP header should indicate the value specified by the suggestedContentType from the response in step 2.

Example Request

Based on the example response in step 2, this should be the request:

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

Retrieve Assets

Single Asset

Method	Endpoint	Description
GET	/v4/assets/{assetId}	Returns a single asset (specified by {assetId}).

Examples

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

List of Assets

Method	Endpoint	Description
GET	/v4/assets	Retuns a list of assets.

Examples

# Getting a list of assets
curl --request GET \
  --url https://{{subdomain}}.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 endpoints.

Update Assets

You can upload a new version of an asset's binary file or update the asset's metadata.

Asset Metadata

Method	Endpoint	Description
POST	/v4/assets/{assetId}	Updates basic asset metadata and supports permissions changes, tags management, and management of locale properties.

Example

curl --request POST \
  --url https://{{subdomain}}.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": "the description",
    "permissions": {
      "isShareable": true
    },
    "isProcessedUsed": true,
    "isDivisionShared": false,
    "isSensitive": false,
    "isArchived": false,
    "isRenderExternalAllowed": true,
    "tags": [
      {
        "id": "df391e1da6ed4db8a8085838f7abd130"
      }
    ],
    "languages": [
      {
        "code": "en"
      }
    ],
    "countries": [
      {
        "code": "US"
      }
    ],
    "authors": [
      {
        "id": "83a5a807b3c487c91f39d1c3da00b5d6"
      }
    ],
    "downloadableExternal": [
      "original"
    ],
    "downloadableInternal": [
      "original"
    ]
  }'

Check out API Specification for a full overview of all data that can be passed in the request body.

Delete Assets

warning

This is an irreversible action. Deleting an asset will permanently remove it from Showpad. Once an asset has been deleted, it can't be recovered.

Method	Endpoint	Description
DELETE	/v4/assets/{assetId}	Permanently removes the asset from Showpad.

Example

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

Tags

Tags are labels that you can add to your assets that allow you to categorize, manage, and find assets quickly.

Create tag

curl --request POST \
  --url https://{{subdomain}}.api.showpad.com/v4/tags \
  --header ‘Authorization: Bearer MyApiToken’ \
  --header ‘Content-Type: application/json’ \
  --data ‘{
  “name”: “my-tag”,
  “division”: {
    “id”: “f541710283954a89bdfd40f221882451”
  },
  “origin”: “{\n  \“type\“: \“oauth2client\“\n}\n”
}’

Get list of tags

curl --request GET \
  --url https://{{subdomain}}.api.showpad.com/v4/tags \
  --header ‘Authorization: Bearer MyApiToken’ \
  --header ‘Content-Type: application/json’

Get single tag

  curl --request GET \
    --url https://{{subdomain}}.api.showpad.com/v4/tags/951aca1a3576e1d1488f29e74756ee60 \
    --header ‘Authorization: Bearer MyApiToken’ \
    --header ‘Content-Type: application/json’

Add tag to an asset

curl --request POST \
  --url https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65 \
  --header ‘Authorization: Bearer MyApiToken’ \
  --header ‘Content-Type: application/json’ \
  --data ‘{
    “tags”: [
      {
        “id”: “df391e1da6ed4db8a8085838f7abd130”
      }
    ],
  }’

Add Assets to My Files

This process uses v3 calls.

In order to push content to a user's My Files folder, you need to make three requests:

	Method	Endpoint	Description
1.	GET	v3/users	Retrieve the user's identifier.
2.	GET	v3/users/{USER_ID}	Retrieve the user's "My Files" identifier. This is their personal division.
3.	POST	v3/divisions/{myUploadsDivisionId/}assets	Upload and link the asset.

1. User Details

curl --request GET \
  --url https://{{subdomain}}.showpad.biz/api/v3/users.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'
  --data '{
    "email": "john.q@public.com"
     }'

Response Example

{
  "meta": {
    "code": 200,
    "message": "OK",
    "serverTime": "2017-09-27T11:49:20+00:00",
    "lastUpdatedTime": "2017-09-27T11:49:20+00:00",
    "requestRateLimit": 5000,
    "requestRateLimitReset": 86400,
    "requestsRemaining": 4915
  },
  "response": {
    "count": 1,
    "items": [
      {
        "id": "322c5a6f89b45933243f3f6281e7f3c2",
        "resourcetype": "User",
        "href": "https://mycompany.showpad-dev.biz/api/v3/users/322c5a6f89b45933243f3f6281e7f3c2",
        "userName": "promoted.user@showpad.com"
      }
    ]
  }
}

2. My Files

curl --request GET \
  --url https://{{subdomain}}.showpad.biz/api/v3/users/{USER_ID}.json \
  --header 'Authorization: Bearer MyApiToken' \
  --header 'Content-Type: application/json'
  --data '{
    "fields": "myUploadsDivisionId"
     }'

Response Example

{
  "meta": {
    "code": 200,
    "message": "OK",
    "serverTime": "2017-10-02T09:43:06+00:00",
    "lastUpdatedTime": "2017-10-02T09:43:06+00:00",
    "requestRateLimit": 5000,
    "requestRateLimitReset": 86400,
    "requestsRemaining": 5000
  },
  "response": {
    "myUploadsDivisionId": "4d3716141c8ffb76928e602548fb9f1c"
  }
}

3. Upload and Link

You're now ready to upload the asset and link it to the user's personal division (My Files). Before you do so, you should be aware that:

• If you're an administrator, you're only able to POST content. Other request types are not permitted.

• If an asset already exists in the same division, a 409 validation error (conflict) is returned.

• If you're uploading an asset that needs processing (e.g. PDF, Word, Excel, Powerpoint, etc), you'll get a Ticket ID as a response. Continue polling this ticket resource every 30 seconds until you get a valid Asset ID. More information about file processing is available here.

• It's important to note that the following parameters are required:

  • postProcessingInstructions - This is a JSON object containing the folderId where you want to push the file to. You can get the folderId from the URL when navigating to the correct path in your My Files tab). For example:

    {materializedPath: "/7843b4523ecc64d16dad3043505d6190c897c77f81258080c04d66de4e131e77/"}`)

    For the root folder, you can use {materializedPath: "/"}.

  • isPersonal="true" - This indicates that the file is personal.

Request Example

curl --request POST \
--url 'https://{{subdomain}}.showpad.biz/api/v3/divisions/{myUploadsDivisionId/}/assets.json' \
--header 'Authorization: Bearer MyApiToken' \
--form 'description="Custom description of my file"' \
--form 'file=@"/Users/johnqpublic/Downloads/image (40).png"' \
--form 'isPersonal="true"' \
--form 'name="Custom name for my file"' \
--form 'postProcessingInstructions="{ \"materialisedPath\": \"/\"}"'

You can find the full list of available form options in the reference.

tip

Users uploading to their own "My Files" can replace myUploadsDivisionId with mine.

Response Example

{
  "meta": {
    "code": 0,
    "message": "string",
    "serverTime": "2019-08-24",
    "lastUpdatedTime": "2019-08-24",
    "requestRateLimit": 0,
    "requestRateLimitReset": 0,
    "requestsRemaining": 0
  },
  "response": {
    "id": "string",
    "resourcetype": "string",
    "createdAt": "2019-08-24",
    "description": "string",
    "division": "string",
    "downloadLink": "string",
    "shortLivedDownloadLink": "string",
    "shortLivedDownloadDuration": 0,
    "externalId": "string",
    "fileSize": 0,
    "filetype": "string",
    "isAnnotatable": true,
    "isSensitive": true,
    "isShareable": true,
    "isDownloadable": true,
    "isDivisionShared": true,
    "useOptimized": true,
    "name": "string",
    "url": "string",
    "originalName": "string",
    "previewDownloadLink": "string",
    "thumbnailDownloadLink": "string",
    "tags": "string",
    "assetView": "string",
    "updatedAt": "2019-08-24",
    "views": 0,
    "appLink": "string",
    "liked": true,
    "likesCount": 0,
    "standardId": "string",
    "externalDate": "2019-08-24",
    "archivedAt": "2019-08-24",
    "expiresAt": "2019-08-24",
    "releasedAt": "2019-08-24",
    "extension": "string",
    "lockedPages": ["string"],
    "pageCount": 0,
    "onlyShareEntireDocument": true,
    "isPersonal": true,
    "isMarketing": true,
    "externalServiceId": "string",
    "currentChannelTemplateConfigId": "string",
    "slug": "string",
    "hideLabel": true,
    "isEditable": true,
    "sourceAsset": "string",
    "sourceAssetName": "string",
    "sourceAssetLink": "string",
    "videoLength": 0,
    "duration": 0,
    "allowRenderExternal": true,
    "downloadableInternal": ["string"],
    "downloadableExternal": ["string"],
    "md5Checksum": "string",
    "fileUuid": "string",
    "version": 0,
    "parentAssetId": "string",
    "oAuth2ClientId": "string"
  }
}