> ## Documentation Index
> Fetch the complete documentation index at: https://www.canva.dev/docs/apps/llms.txt
> Use this file to discover all available pages before exploring further.

# List folder items

List the contents of a folder.

Lists the items in a folder, including each item's `type`.

Folders can contain:

* Other folders.
* Designs, such as Instagram posts, Presentations, and Documents ([Canva Docs](https://www.canva.com/create/documents/)).
* Image assets.
* Brand templates. To include `brand_template` items in the response, you must explicitly specify it in the `item_types` parameter.

  AVAILABILITY: Brand template items are only returned for users on a Canva plan with access to brand templates (such as Canva Pro, Canva Teams, or Canva Enterprise). For more information, see [Brand templates](https://www.canva.dev/docs/apps/rest-apis/reference/brand-templates/).

Currently, video assets are not returned in the response.

## HTTP method and URL path

GET https\://api.canva.com/rest/v1/folders/\{folderId}/items

This operation is rate limited to 100 requests per minute for each user of your app.

## Authentication and authorization

This endpoint requires a valid access token that acts on behalf of a user. For more information, see [Generate an access token](/docs/apps/rest-apis/reference/authentication/generate-access-token).

### Scopes

The access token must have all the following [scopes](/docs/apps/rest-apis/scopes) (permissions):

* `folder:read`

## Header parameters

<Prop.List>
  <Prop name="Authorization" type="string" required>
    Provides credentials to authenticate the request, in the form of a `Bearer` token.

    For example: `Authorization: Bearer {token}`
  </Prop>
</Prop.List>

## Path parameters

<Prop.List>
  <Prop name="folderId" type="string" required>
    The folder ID.
  </Prop>
</Prop.List>

## Query parameters

<Prop.List>
  <Prop name="continuation" type="string">
    If the success response contains a continuation token, the folder contains more items
    you can list. You can use this token as a query parameter and retrieve more
    items from the list, for example
    `/v1/folders/{folderId}/items?continuation={continuation}`.

    To retrieve all the items in a folder, you might need to make multiple requests.
  </Prop>

  <Prop name="limit" type="integer">
    The number of folder items to return.

    <Prop.Extras>
      **Minimum:** `1`

      **Maximum:** `100`

      **Default value:** `50`
    </Prop.Extras>
  </Prop>

  <Prop name="item_types" type="string[]">
    Filter the folder items to only return specified types. The available types are:
    `design`, `folder`, `image`, and `brand_template`. To filter for more than one item type,
    provide a comma-delimited list.

    If not specified, defaults to returning `design`, `folder`, and `image` items.
    To include `brand_template` items, you must explicitly specify it in this parameter.

    <Prop.Extras>
      **Default value:** `["design", "folder", "image"]`

      **Available values:**

      * `design`
      * `folder`
      * `image`
      * `brand_template`
    </Prop.Extras>
  </Prop>

  <Prop name="sort_by" type="string">
    Sort the list of folder items.

    <Prop.Extras>
      **Default value:** `modified_descending`

      **Available values:**

      * `created_ascending`: Sort results by creation date, in ascending order.
      * `created_descending`: Sort results by creation date, in descending order.
      * `modified_ascending`: Sort results by the last modified date, in ascending order.
      * `modified_descending`: Sort results by the last modified date, in descending order.
      * `title_ascending`: Sort results by title, in ascending order. The title is either the `name` field for a folder or asset, or the `title` field for a design or brand template.
      * `title_descending`: Sort results by title, in descending order. The title is either the `name` field for a folder or asset, or the `title` field for a design or brand template.
    </Prop.Extras>
  </Prop>

  <Prop name="pin_status" type="string">
    Filter folder items by their pinned status.

    <Prop.Extras>
      **Default value:** `any`

      **Available values:**

      * `any`: Return all items regardless of pinned status (default).
      * `pinned`: Return only pinned items.
    </Prop.Extras>
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/folders/{folderId}/items` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request GET 'https://api.canva.com/rest/v1/folders/{folderId}/items' \
    --header 'Authorization: Bearer {token}'
    ```
  </Tab>

  <Tab name="Node.js">
    ```js
    const fetch = require("node-fetch");

    fetch("https://api.canva.com/rest/v1/folders/{folderId}/items", {
      method: "GET",
      headers: {
        "Authorization": "Bearer {token}",
      },
    })
      .then(async (response) => {
        const data = await response.json();
        console.log(data);
      })
      .catch(err => console.error(err));
    ```
  </Tab>

  <Tab name="Java">
    ```java
    import java.io.IOException;
    import java.net.URI;
    import java.net.http.*;

    public class ApiExample {
        public static void main(String[] args) throws IOException, InterruptedException {
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.canva.com/rest/v1/folders/{folderId}/items"))
                .header("Authorization", "Bearer {token}")
                .method("GET", HttpRequest.BodyPublishers.noBody())
                .build();

            HttpResponse<String> response = HttpClient.newHttpClient().send(
                request,
                HttpResponse.BodyHandlers.ofString()
            );
            System.out.println(response.body());
        }
    }
    ```
  </Tab>

  <Tab name="Python">
    ```py
    import requests

    headers = {
        "Authorization": "Bearer {token}"
    }

    response = requests.get("https://api.canva.com/rest/v1/folders/{folderId}/items",
        headers=headers
    )
    print(response.json())
    ```
  </Tab>

  <Tab name="C#">
    ```csharp
    using System.Net.Http;

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Get,
      RequestUri = new Uri("https://api.canva.com/rest/v1/folders/{folderId}/items"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
      },
    };

    using (var response = await client.SendAsync(request))
    {
      response.EnsureSuccessStatusCode();
      var body = await response.Content.ReadAsStringAsync();
      Console.WriteLine(body);
    };
    ```
  </Tab>

  <Tab name="Go">
    ```go
    package main

    import (
    	"fmt"
    	"io"
    	"net/http"
    )

    func main() {
    	url := "https://api.canva.com/rest/v1/folders/{folderId}/items"
    	req, _ := http.NewRequest("GET", url, nil)
    	req.Header.Add("Authorization", "Bearer {token}")

    	res, _ := http.DefaultClient.Do(req)
    	defer res.Body.Close()
    	body, _ := io.ReadAll(res.Body)
    	fmt.Println(string(body))
    }
    ```
  </Tab>

  <Tab name="PHP">
    ```php
    $curl = curl_init();
    curl_setopt_array($curl, array(
      CURLOPT_URL => "https://api.canva.com/rest/v1/folders/{folderId}/items",
      CURLOPT_CUSTOMREQUEST => "GET",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
      ),
    ));

    $response = curl_exec($curl);
    $err = curl_error($curl);
    curl_close($curl);

    if (empty($err)) {
      echo $response;
    } else {
      echo "Error: " . $err;
    }
    ```
  </Tab>

  <Tab name="Ruby">
    ```ruby
    require 'net/http'
    require 'uri'

    url = URI('https://api.canva.com/rest/v1/folders/{folderId}/items')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Get.new(url)
    request['Authorization'] = 'Bearer {token}'

    response = http.request(request)
    puts response.read_body
    ```
  </Tab>
</Tabs>

## Success response

If successful, the endpoint returns a `200` response with a JSON body with the following parameters:

<Prop.List>
  <Prop name="items" type="FolderItemSummary[]" required mode="output">
    An array of items in the folder.

    <Tabs>
      <Tab name="folder">
        Details about the folder.

        <Prop.List>
          <Prop name="type" type="string" required mode="output">
            <Prop.Extras>
              **Available values:** The only valid value is `folder`.
            </Prop.Extras>
          </Prop>

          <Prop name="folder" type="Folder" required mode="output">
            The folder object, which contains metadata about the folder.

            <PillAccordion title={<>Properties of <strong>folder</strong></>}>
              <Prop.List>
                <Prop name="id" type="string" required mode="output">
                  The folder ID.
                </Prop>

                <Prop name="name" type="string" required mode="output">
                  The folder name.
                </Prop>

                <Prop name="created_at" type="integer" required mode="output">
                  When the folder was created, as a Unix timestamp (in seconds since the
                  Unix Epoch).
                </Prop>

                <Prop name="updated_at" type="integer" required mode="output">
                  When the folder was last updated, as a Unix timestamp (in seconds since the
                  Unix Epoch).
                </Prop>

                <Prop name="thumbnail" type="Thumbnail" mode="output">
                  A thumbnail image representing the object.

                  <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                    <Prop.List>
                      <Prop name="width" type="integer" required mode="output">
                        The width of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="height" type="integer" required mode="output">
                        The height of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="url" type="string" required mode="output">
                        A URL for retrieving the thumbnail image.
                        This URL expires after 15 minutes. This URL includes a query string
                        that's required for retrieving the thumbnail.
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="design">
        Details about the design.

        <Prop.List>
          <Prop name="type" type="string" required mode="output">
            <Prop.Extras>
              **Available values:** The only valid value is `design`.
            </Prop.Extras>
          </Prop>

          <Prop name="design" type="DesignSummary" required mode="output">
            Basic details about the design, such as the design's ID, title, and URL.

            <PillAccordion title={<>Properties of <strong>design</strong></>}>
              <Prop.List>
                <Prop name="id" type="string" required mode="output">
                  The design ID.
                </Prop>

                <Prop name="urls" type="DesignLinks" required mode="output">
                  A temporary set of URLs for viewing or editing the design.

                  <PillAccordion title={<>Properties of <strong>urls</strong></>}>
                    <Prop.List>
                      <Prop name="edit_url" type="string" required mode="output">
                        A temporary editing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.

                        NOTE: This is not a permanent URL, it is only valid for 30 days.
                      </Prop>

                      <Prop name="view_url" type="string" required mode="output">
                        A temporary viewing URL for the design. This URL is only accessible to the user that made the API request, and is designed to support [return navigation](https://www.canva.dev/docs/apps/rest-apis/return-navigation-guide/) workflows.

                        NOTE: This is not a permanent URL, it is only valid for 30 days.
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>

                <Prop name="created_at" type="integer" required mode="output">
                  When the design was created in Canva, as a Unix timestamp (in seconds since the Unix
                  Epoch).
                </Prop>

                <Prop name="updated_at" type="integer" required mode="output">
                  When the design was last updated in Canva, as a Unix timestamp (in seconds since the
                  Unix Epoch).
                </Prop>

                <Prop name="title" type="string" mode="output">
                  The design title.
                </Prop>

                <Prop name="url" type="string" mode="output">
                  URL of the design.
                </Prop>

                <Prop name="thumbnail" type="Thumbnail" mode="output">
                  A thumbnail image representing the object.

                  <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                    <Prop.List>
                      <Prop name="width" type="integer" required mode="output">
                        The width of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="height" type="integer" required mode="output">
                        The height of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="url" type="string" required mode="output">
                        A URL for retrieving the thumbnail image.
                        This URL expires after 15 minutes. This URL includes a query string
                        that's required for retrieving the thumbnail.
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>

                <Prop name="page_count" type="integer" mode="output">
                  The total number of pages in the design. Some design types don't have pages (for example, Canva docs).
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="image">
        Details about the image asset.

        <Prop.List>
          <Prop name="type" type="string" required mode="output">
            <Prop.Extras>
              **Available values:** The only valid value is `image`.
            </Prop.Extras>
          </Prop>

          <Prop name="image" type="AssetSummary" required mode="output">
            An object representing an asset with associated metadata.

            <PillAccordion title={<>Properties of <strong>image</strong></>}>
              <Prop.List>
                <Prop name="type" type="string" required mode="output">
                  Type of an asset.

                  <Prop.Extras>
                    **Available values:**

                    * `image`
                    * `video`
                  </Prop.Extras>
                </Prop>

                <Prop name="id" type="string" required mode="output">
                  The ID of the asset.
                </Prop>

                <Prop name="name" type="string" required mode="output">
                  The name of the asset.
                </Prop>

                <Prop name="tags" type="string[]" required mode="output">
                  The user-facing tags attached to the asset.
                  Users can add these tags to their uploaded assets, and they can search their uploaded
                  assets in the Canva UI by searching for these tags. For information on how users use
                  tags, see the
                  [Canva Help Center page on asset tags](https://www.canva.com/help/add-edit-tags/).
                </Prop>

                <Prop name="created_at" type="integer" required mode="output">
                  When the asset was added to Canva, as a Unix timestamp (in seconds since the Unix
                  Epoch).
                </Prop>

                <Prop name="updated_at" type="integer" required mode="output">
                  When the asset was last updated in Canva, as a Unix timestamp (in seconds since the
                  Unix Epoch).
                </Prop>

                <Prop name="thumbnail" type="Thumbnail" mode="output">
                  A thumbnail image representing the object.

                  <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                    <Prop.List>
                      <Prop name="width" type="integer" required mode="output">
                        The width of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="height" type="integer" required mode="output">
                        The height of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="url" type="string" required mode="output">
                        A URL for retrieving the thumbnail image.
                        This URL expires after 15 minutes. This URL includes a query string
                        that's required for retrieving the thumbnail.
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>

      <Tab name="brand_template">
        Details about the brand template.

        <Prop.List>
          <Prop name="type" type="string" required mode="output">
            <Prop.Extras>
              **Available values:** The only valid value is `brand_template`.
            </Prop.Extras>
          </Prop>

          <Prop name="brand_template" type="BrandTemplateSummary" required mode="output">
            An object representing a brand template with associated metadata.

            <PillAccordion title={<>Properties of <strong>brand_template</strong></>}>
              <Prop.List>
                <Prop name="id" type="string" required mode="output">
                  The brand template ID.
                </Prop>

                <Prop name="title" type="string" required mode="output">
                  The brand template title, as shown in the Canva UI.
                </Prop>

                <Prop name="view_url" type="string" required mode="output">
                  A URL Canva users can visit to view the brand template.
                </Prop>

                <Prop name="create_url" type="string" required mode="output">
                  A URL Canva users can visit to create a new design from the template.
                </Prop>

                <Prop name="created_at" type="integer" required mode="output">
                  When the brand template was created, as a Unix timestamp
                  (in seconds since the Unix Epoch).
                </Prop>

                <Prop name="updated_at" type="integer" required mode="output">
                  When the brand template was last updated, as a Unix timestamp
                  (in seconds since the Unix Epoch).
                </Prop>

                <Prop name="thumbnail" type="Thumbnail" mode="output">
                  A thumbnail image representing the object.

                  <PillAccordion title={<>Properties of <strong>thumbnail</strong></>}>
                    <Prop.List>
                      <Prop name="width" type="integer" required mode="output">
                        The width of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="height" type="integer" required mode="output">
                        The height of the thumbnail image in pixels.
                      </Prop>

                      <Prop name="url" type="string" required mode="output">
                        A URL for retrieving the thumbnail image.
                        This URL expires after 15 minutes. This URL includes a query string
                        that's required for retrieving the thumbnail.
                      </Prop>
                    </Prop.List>
                  </PillAccordion>
                </Prop>
              </Prop.List>
            </PillAccordion>
          </Prop>
        </Prop.List>
      </Tab>
    </Tabs>
  </Prop>

  <Prop name="continuation" type="string" mode="output">
    If the success response contains a continuation token, the folder contains more items
    you can list. You can use this token as a query parameter and retrieve more
    items from the list, for example
    `/v1/folders/{folderId}/items?continuation={continuation}`.

    To retrieve all the items in a folder, you might need to make multiple requests.
  </Prop>
</Prop.List>

## Example response

```json
{
  "items": [
    {
      "type": "folder",
      "folder": {
        "id": "FAF2lZtloor",
        "name": "My awesome holiday",
        "created_at": 1377396000,
        "updated_at": 1692928800,
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        }
      }
    },
    {
      "type": "design",
      "design": {
        "id": "DAFVztcvd9z",
        "title": "My summer holiday",
        "url": "https://www.canva.com/design/DAFVztcvd9z/edit",
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        },
        "urls": {
          "edit_url": "https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/edit",
          "view_url": "https://www.canva.com/api/design/eyJhbGciOiJkaXIiLCJlbmMiOiJBMjU2R0NNIiwiZXhwaXJ5IjoxNzQyMDk5NDAzMDc5fQ..GKLx2hrJa3wSSDKQ.hk3HA59qJyxehR-ejzt2DThBW0cbRdMBz7Fb5uCpwD-4o485pCf4kcXt_ypUYX0qMHVeZ131YvfwGPIhbk-C245D8c12IIJSDbZUZTS7WiCOJZQ.sNz3mPSQxsETBvl_-upMYA/view"
        },
        "created_at": 1377396000,
        "updated_at": 1692928800,
        "page_count": 3
      }
    },
    {
      "type": "image",
      "image": {
        "type": "image",
        "id": "Msd59349ff",
        "name": "My Awesome Upload",
        "tags": [
          "image",
          "holiday",
          "best day ever"
        ],
        "created_at": 1377396000,
        "updated_at": 1692928800,
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        }
      }
    },
    {
      "type": "brand_template",
      "brand_template": {
        "id": "DEMzWSwy3BI",
        "title": "Advertisement Template",
        "view_url": "https://www.canva.com/design/DAE35hE8FA4/view",
        "create_url": "https://www.canva.com/design/DAE35hE8FA4/remix",
        "thumbnail": {
          "width": 595,
          "height": 335,
          "url": "https://document-export.canva.com/Vczz9/zF9vzVtdADc/2/thumbnail/0001.png?<query-string>"
        },
        "created_at": 1704110400,
        "updated_at": 1719835200
      }
    }
  ],
  "continuation": "RkFGMgXlsVTDbMd:MR3L0QjiaUzycIAjx0yMyuNiV0OildoiOwL0x32G4NjNu4FwtAQNxowUQNMMYN"
}
```

## Error responses

### 400 Bad Request

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error response

##### The provided continuation token is invalid

```json
{
  "code": "bad_query_params",
  "message": "{message}"
}
```

### 403 Forbidden

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error response

##### Not allowed to access the folder

```json
{
  "code": "permission_denied",
  "message": "{message}"
}
```

### 404 Not Found

<Prop.List>
  <Prop name="code" type="string" required mode="output">
    A short string indicating what failed. This field can be used to handle errors programmatically. For a complete list of error codes, see [Error responses](/docs/apps/rest-apis/error-responses/).
  </Prop>

  <Prop name="message" type="string" required mode="output">
    A human-readable description of what went wrong.
  </Prop>
</Prop.List>

#### Example error response

##### The folder was not found

```json
{
  "code": "folder_not_found",
  "message": "Folder not found"
}
```