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/v4

Every API v4 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`	`/assets`	Generates an asset ID for the new asset.
2.	`POST`	`/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`	`/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`	`/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`	`/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`	`/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'

Add Assets to My Files

info

This process uses v3 calls with a different base endpoint.

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

	Method	Endpoint	Description
1.	`GET`	`https://{{subdomain}}.showpad.biz/api/v3/users`	Retrieve the user's identifier.
2.	`GET`	`https://{{subdomain}}.showpad.biz/api/v3/users/{USER_ID}`	Retrieve the user's "My Files" identifier. This is their personal division.
3.	`POST`	`https://{{subdomain}}.showpad.biz/api/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"
  }
}

Asset Management

Base Endpoint

Create Assets

1. Asset ID

2. Asset File

3. Upload Binary

Retrieve Assets

Single Asset

List of Assets

Update Assets

Asset Metadata

Delete Assets

Tags

Create tag

Get list of tags

Get single tag

Add tag to an asset

Add Assets to My Files

1. User Details

2. My Files

3. Upload and Link

Base Endpoint​

Create Assets​

1. Asset ID​

2. Asset File​

3. Upload Binary​

Retrieve Assets​

Single Asset​

List of Assets​

Update Assets​

Asset Metadata​

Delete Assets​

Tags​

Create tag​

Get list of tags​

Get single tag​

Add tag to an asset​

Add Assets to My Files​

1. User Details​

2. My Files​

3. Upload and Link​

Base Endpoint

Create Assets

1. Asset ID

2. Asset File

3. Upload Binary

Retrieve Assets

Single Asset

List of Assets

Update Assets

Asset Metadata

Delete Assets

Tags

Create tag

Get list of tags

Get single tag

Add tag to an asset

Add Assets to My Files

1. User Details

2. My Files

3. Upload and Link