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.

What you'll learn:

Create, retrieve, update, and delete assets
Manage asset metadata, permissions, and tags
Upload files to the content library and My Files

TL;DR

Upload a file? Use POST /assets with multipart form data. Returns the new asset ID.
Update metadata? Use PATCH /assets/:id. Only send the fields you want to change.
Add tags? Use POST /assets/:id/tags. Link existing tags by ID.
Query assets? Use ShowQL. Filter by Division, tags, metadata, and more.

When to use the API

Use the Showpad API when you need to:

Migrate content	Bulk uploads	Sync content	Integrate with workflows
Move assets from another platform or system into Showpad	Upload multiple files programmatically instead of adding them one by one	Keep Showpad in sync with an external CMS or content repository	Trigger asset updates based on external events or business processes

For one-off uploads or small updates, the Showpad Admin App is often faster.

Prerequisites

Plan: Ultimate | Advanced or Expert
Permissions: Administrator access to Showpad's Admin App
Authentication: Valid OAuth 2.0 access token (learn more)

Base Endpoint

The base endpoint for v4 requests is:

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

Every API v4 request needs to be prefixed with the base endpoint.

CORS

Showpad adopts a strict approach for cross-origin requests. Only requests from your valid Showpad domain are allowed.

Create Assets

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

Create Asset Flow

	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
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'My Document.pdf',
    division: {
      id: 'f541710283954a89bdfd40f221882451',
    },
    externalId: 'my-custom-id',
    description: 'string',
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
data = {
    "name": "My Document.pdf",
    "division": {
        "id": "f541710283954a89bdfd40f221882451"
    },
    "externalId": "my-custom-id",
    "description": "string"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

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
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65/files', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'video.mp4',
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65/files"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
data = {
    "name": "video.mp4"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

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
JavaScript
Python

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

const fileBuffer = await fs.promises.readFile('/path/to/video.mp4');

const response = await fetch('https://s3.amazonaws.com/path/to/bucket/with/signed/credentials', {
  method: 'PUT',
  headers: {
    'Content-Type': 'video/mp4',
  },
  body: fileBuffer,
});

console.log('Upload complete:', response.status);

import requests

url = "https://s3.amazonaws.com/path/to/bucket/with/signed/credentials"
headers = {
    "Content-Type": "video/mp4"
}

with open("/path/to/video.mp4", "rb") as file:
    response = requests.put(url, data=file, headers=headers)
    print("Upload complete:", response.status_code)

Retrieve Assets

Single Asset

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

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/cc55b0cf8eef46f71d3a6398734e0611', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/cc55b0cf8eef46f71d3a6398734e0611"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

List of Assets

Method	Endpoint	Description
`GET`	`/assets`	Returns a list of assets.

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.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
JavaScript
Python

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"
    ]
  }'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    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'],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65"
headers = {
    "Authorization": "Bearer MyApiToken",
    "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"]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

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
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

console.log('Delete status:', response.status);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print("Delete status:", response.status_code)

Tags

Tags let you categorize and organize your assets for easier discovery and filtering. You can create tags, assign them to assets, and use them in ShowQL queries to find specific content.

For more information about using tags in Showpad, see Add tags to label and categorize your content.

Method	Endpoint	Description
`POST`	`/tags`	Creates a new tag.
`GET`	`/tags`	Returns a list of tags.
`GET`	`/tags/{tagId}`	Returns a single tag.
`DELETE`	`/tags/{tagId}`	Deletes a tag.
`POST`	`/assets/{assetId}`	Adds or removes tags from an asset.

Create tag

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/tags', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'my-tag',
    division: { id: 'f541710283954a89bdfd40f221882451' },
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/tags"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
data = {
    "name": "my-tag",
    "division": {"id": "f541710283954a89bdfd40f221882451"}
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Get list of tags

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/tags', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/tags"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Get single tag

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/tags/951aca1a3576e1d1488f29e74756ee60', {
  method: 'GET',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/tags/951aca1a3576e1d1488f29e74756ee60"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, headers=headers)
print(response.json())

Delete tag

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/tags/951aca1a3576e1d1488f29e74756ee60', {
  method: 'DELETE',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
});

console.log('Delete status:', response.status);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/tags/951aca1a3576e1d1488f29e74756ee60"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.delete(url, headers=headers)
print("Delete status:", response.status_code)

Add tag to an asset

Example

cURL
JavaScript
Python

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"
      }
    ]
  }'

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tags: [{ id: 'df391e1da6ed4db8a8085838f7abd130' }],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
data = {
    "tags": [{"id": "df391e1da6ed4db8a8085838f7abd130"}]
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Remove tag from an asset

To remove a tag, update the asset with the tags you want to keep (excluding the one to remove).

Example

cURL
JavaScript
Python

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

const response = await fetch('https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    tags: [],
  }),
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.api.showpad.com/v4/assets/422bb79a5e8347d1bf93a5d3306bda65"
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}
data = {
    "tags": []
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Add Assets to My Files

caution

This process is only available via v3 calls which use a different base endpoint. Note that while some endpoints may be deprecated, they continue to work.

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

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

1. User Details

cURL
JavaScript
Python

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

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/users.json?' + new URLSearchParams({ email: 'john.q@public.com' }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer MyApiToken',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/users.json"
params = {"email": "john.q@public.com"}
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

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
JavaScript
Python

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

const response = await fetch(
  'https://{{subdomain}}.showpad.biz/api/v3/users/{USER_ID}.json?' +
    new URLSearchParams({ fields: 'myUploadsDivisionId' }),
  {
    method: 'GET',
    headers: {
      Authorization: 'Bearer MyApiToken',
      'Content-Type': 'application/json',
    },
  }
);

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/users/{USER_ID}.json"
params = {"fields": "myUploadsDivisionId"}
headers = {
    "Authorization": "Bearer MyApiToken",
    "Content-Type": "application/json"
}

response = requests.get(url, params=params, headers=headers)
print(response.json())

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
JavaScript
Python

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.png"' \
  --form 'isPersonal="true"' \
  --form 'name="Custom name for my file"' \
  --form 'postProcessingInstructions="{ \"materialisedPath\": \"/\"}"'

const formData = new FormData();
formData.append('description', 'Custom description of my file');
formData.append('file', fileBlob, 'image.png'); // fileBlob from File input or fs
formData.append('isPersonal', 'true');
formData.append('name', 'Custom name for my file');
formData.append('postProcessingInstructions', '{ "materialisedPath": "/" }');

const response = await fetch('https://{{subdomain}}.showpad.biz/api/v3/divisions/{myUploadsDivisionId}/assets.json', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer MyApiToken',
  },
  body: formData,
});

const data = await response.json();
console.log(data);

import requests

url = "https://{{subdomain}}.showpad.biz/api/v3/divisions/{myUploadsDivisionId}/assets.json"
headers = {
    "Authorization": "Bearer MyApiToken"
}

with open("/Users/johnqpublic/Downloads/image.png", "rb") as file:
    files = {"file": ("image.png", file)}
    data = {
        "description": "Custom description of my file",
        "isPersonal": "true",
        "name": "Custom name for my file",
        "postProcessingInstructions": '{ "materialisedPath": "/" }'
    }
    response = requests.post(url, headers=headers, files=files, data=data)
    print(response.json())

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

Troubleshooting

If a request fails, check that the asset ID exists and the user has Administrator access to the Admin App. If an upload URL expires, request a new one by repeating step 2. For a complete list of error codes and response formats, see Error Codes.

Next Steps

Now that you understand how to manage assets, explore these related topics:

ShowQL - Query and filter assets using Showpad's human-readable query language.
Content Recommendations - Retrieve ranked lists of new, popular, trending, and updated assets.
API Reference - Full API specification for all asset endpoints.

Was this page helpful?

When to use the API​

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​

Delete tag​

Add tag to an asset​

Remove tag from an asset​

Add Assets to My Files​

1. User Details​

2. My Files​

3. Upload and Link​

Troubleshooting​

Next Steps​

When to use the API

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

Delete tag

Add tag to an asset

Remove tag from an asset

Add Assets to My Files

1. User Details

2. My Files

3. Upload and Link

Troubleshooting

Next Steps