Getting design list

Last updated on May 15, 2025
•
5 minutes to read

To get a list of designs in a storage, use the endpoint GET /api/storage/v1/designs. This endpoint uses a tenantId query parameter and returns the design list for a single tenant. However, if you don't specify it explicitly, then the tenantId will be determined by your credentials.

curl -X \
  GET "https://api.customerscanvashub.com/api/storage/v1/designs" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storage/v1/designs

var designList = await designsApiClient.GetAllAsync();

var designList = await _designsApiClient.getAll();

$designList = $designsApiClient->designsGetAll();

Filtering a design list

If you call this endpoint without any parameters, you will get all designs available in your tenant. However, you usually need to show a limited list of designs, e.g., only letter-size format or the designs belonging to a particular category. Let's take a look at the filtering options.

By folders

You may organize your designs in folders in accordance to the structure of your products or categories. For example, you may have folders like

/Commercial Printing
   /Business Cards
   /Letter-size Flyer
   /Tabloid-size Poster
   ...
/Stickers
   /Rectangular
      /1x1
      /2x2
      /2x3
      /3x3
      ...
   /Ellipse
      /1x1
      /2x2
      /2x3
      ...

In each folder, you will have designs for a specific size and product type.

When a user orders, say, a letter-size flyer, you need to use a path parameter of GET /api/storage/v1/designs and send /Commercial Printing/Letter-size Flyer.

You may also send an includeSubfolders parameter (true or false) to specify whether you need to return files only from this particular folder or select designs from subfolders.

curl -X \
  GET "https://api.customerscanvashub.com/api/storage/v1/designs?path=%2FCommercial%20Printing%2FLetter-size%20Flyer&includeSubfolders=false" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storage/v1/designs?path=%2FCommercial%20Printing%2FLetter-size%20Flyer&includeSubfolders=false

var folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
var subfolders = false; // Change to `true` if needed
var designList = await designsApiClient.GetAllAsync(path: folder, includeSubfolders: subfolders);

var folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
var subfolders = false; // Change to `true` if needed
var designList = await _designsApiClient.getAll(null, null, folder, subfolders);

$folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
$subfolders = false; // Change to `true` if needed
$designList = $designsApiClient->designsGetAll(null, null, $folder, $subfolders);

If you prefer to build a tree view and make the navigation similar to a file manager, you may prefer to use another endpoint: GET /api/storage/v1/designs/folders/content-by-path. Unlike GET /api/storage/v1/designs, you get not only a list of entries in a folder, but also a list of all subfolders. Also, this endpoint has fewer filtering features.

curl -X \
  GET "https://api.customerscanvashub.com/api/storage/v1/designs/folders/content-by-path?fullPath=%2FCommercial%20Printing%2FLetter-size%20Flyer" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storage/v1/designs/folders/content-by-path?fullPath=%2FCommercial%20Printing%2FLetter-size%20Flyer

var folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
var designList = await designsApiClient.GetFolderAsync(folder);

var folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
var designList = await _designsApiClient.getFolder(folder);

$folder = "/Commercial Printing/Letter-size Flyer"; // Put your real path here
$designList = $designsApiClient->designsGetFolder($folder);

By custom fields

Designs stored in Asset Storage support custom fields. You can add them through the endpoint PUT /api/storage/v1/designs/{id}. It allows for adding an arbitrary JSON object as a customFields dictionary to any design, for example:

{
    "Product Type": "Flyer",
    "Category": "Retail"
}

curl -X \
  PUT "https://api.customerscanvashub.com/api/storage/v1/designs/64df0541bc24c7f470b3c286" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>" \
  -H  "Content-Type: multipart/form-data" \
  -F "customFields={\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"

PUT https://api.customerscanvashub.com/api/storage/v1/designs/64df0541bc24c7f470b3c286
{
    "customFields" = {
        "Product Type": "Flyer",
        "Category": "Retail"
    }
}

var designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
var customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
var designList = await designsApiClient.UpdateAsync(designId, customFields: customFields);

var designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
var customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
var designList = await _designsApiClient.update(designId, null, null, null, null, null, null, null, null, null, null, null, customFields);

$designId = "64df0541bc24c7f470b3c286"; // Put your real design ID here
$customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
$designList = $designsApiClient->designsUpdate($designId, null, null, null, null, null, null, null, null, null, null, null, $customFields);

Then, you may pass a JSON object that has been made into a string to the customFields parameter to the GET /api/storage/v1/designs endpoint to return only those values that match the specified fields. For example, to return all designs that have Product Type equal to Flyer, you need to pass the {"Product Type": "Flyer"} string to customFields.

curl -X \
  GET "https://api.customerscanvashub.com/api/storage/v1/designs?customFields=%7B%22Product%20Type%22%3A%20%22Flyer%22%7D" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storage/v1/designs?customFields=%7B%22Product%20Type%22%3A%20%22Flyer%22%7D

var customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
var designList = await designsApiClient.GetAllAsync(customFields: customFields);

var customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
var designList = await _designsApiClient.getAll(null, null, null, null, null, null, null, null, customFields);

$customFields = "{\"Product Type\": \"Flyer\", \"Category\": \"Retail\"}"; // Put your custom fields here
$designList = $designsApiClient->designsGetAll(null, null, null, null, null, null, null, null, $customFields);

By a part of a name

Sometimes you may want to have a search bar where the user can type in a name and narrow down a list of designs to only those that contain specified text as a part of the design name. To do this, use the search parameter of the GET /api/storage/v1/designs endpoint.

curl -X \
  GET "https://api.customerscanvashub.com/api/storage/v1/designs?search=flyer" \
  -H  "accept: application/json" \
  -H  "Authorization: Bearer <TOKEN>"

GET https://api.customerscanvashub.com/api/storage/v1/designs?search=flyer

var designName = "flyer"; // Put a part of a real design name here
var designList = await designsApiClient.GetAllAsync(search: designName);

var designName = "flyer"; // Put a part of a real design name here
var designList = await _designsApiClient.getAll(null, null, null, null, null, null, null, designName);

$designName = "flyer"; // Put a part of a real design name here
$designList = $designsApiClient->designsGetAll(null, null, null, null, null, null, null, $designName);

Design items

Each entry you receive using this API contains a number of fields, for example:

ID
Name
Last modified date
Custom fields
...and others

In addition, it contains the metadata, which is mainly used by Customer's Canvas internally. You may still find it useful, for example, by how many surfaces (pages) it has or what are the dimensions of the design.

It also includes a link to a preview — a crucial element for every design browser interface. We will discuss them in the next section.

Further Reading

Learn how to arranging designs in folders using this API.
Explore how to configure retention policy of assets.
Dive into Asset Storage API reference.