> ## 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.

# Move folder item

Move an item from one folder to another.

Moves an item to another folder. You must specify the folder ID of the destination folder, as well as the ID of the item you want to move.

NOTE: In some situations, a single item can exist in multiple folders. If you attempt to move an item that exists in multiple folders, the API returns an `item_in_multiple_folders` error. In this case, you must use the Canva UI to move the item to another folder.

## HTTP method and URL path

POST https\://api.canva.com/rest/v1/folders/move

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:write`

## 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 name="Content-Type" type="string" required>
    Indicates the media type of the information sent in the request. This must be set to `application/json`.

    For example: `Content-Type: application/json`
  </Prop>
</Prop.List>

## Body parameters

<Prop.List>
  <Prop name="to_folder_id" type="string" required>
    The ID of the folder you want to move the item to (the destination folder).
    If you want to move the item to the top level of a Canva user's
    [projects](https://www.canva.com/help/find-designs-and-folders/), use the ID `root`.

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

      **Maximum length:** `50`
    </Prop.Extras>
  </Prop>

  <Prop name="item_id" type="string" required>
    The ID of the item you want to move. Currently, video assets are not supported.

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

      **Maximum length:** `50`
    </Prop.Extras>
  </Prop>
</Prop.List>

## Example request

Examples for using the `/v1/folders/move` endpoint:

<Tabs storageKey="example.language" disableContentTransition>
  <Tab name="cURL">
    ```sh
    curl --request POST 'https://api.canva.com/rest/v1/folders/move' \
    --header 'Authorization: Bearer {token}' \
    --header 'Content-Type: application/json' \
    --data '{
      "to_folder_id": "FAF2lZtloor",
      "item_id": "Msd59349ff"
    }'
    ```
  </Tab>

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

    fetch("https://api.canva.com/rest/v1/folders/move", {
      method: "POST",
      headers: {
        "Authorization": "Bearer {token}",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        "to_folder_id": "FAF2lZtloor",
        "item_id": "Msd59349ff"
      }),
    })
      .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/move"))
                .header("Authorization", "Bearer {token}")
                .header("Content-Type", "application/json")
                .method("POST", HttpRequest.BodyPublishers.ofString("{\"to_folder_id\": \"FAF2lZtloor\", \"item_id\": \"Msd59349ff\"}"))
                .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}",
        "Content-Type": "application/json"
    }

    data = {
        "to_folder_id": "FAF2lZtloor",
        "item_id": "Msd59349ff"
    }

    response = requests.post("https://api.canva.com/rest/v1/folders/move",
        headers=headers,
        json=data
    )
    print(response.json())
    ```
  </Tab>

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

    var client = new HttpClient();
    var request = new HttpRequestMessage
    {
      Method = HttpMethod.Post,
      RequestUri = new Uri("https://api.canva.com/rest/v1/folders/move"),
      Headers =
      {
        { "Authorization", "Bearer {token}" },
      },
      Content = new StringContent(
        "{\"to_folder_id\": \"FAF2lZtloor\", \"item_id\": \"Msd59349ff\"}",
        Encoding.UTF8,
        "application/json"
      ),
    };

    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"
    	"strings"
    )

    func main() {
    	payload := strings.NewReader(`{
    	  "to_folder_id": "FAF2lZtloor",
    	  "item_id": "Msd59349ff"
    	}`)

    	url := "https://api.canva.com/rest/v1/folders/move"
    	req, _ := http.NewRequest("POST", url, payload)
    	req.Header.Add("Authorization", "Bearer {token}")
    	req.Header.Add("Content-Type", "application/json")

    	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/move",
      CURLOPT_CUSTOMREQUEST => "POST",
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => array(
        'Authorization: Bearer {token}',
        'Content-Type: application/json',
      ),
      CURLOPT_POSTFIELDS => json_encode([
        "to_folder_id" => "FAF2lZtloor",
        "item_id" => "Msd59349ff"
      ])
    ));

    $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/move')
    http = Net::HTTP.new(url.host, url.port)
    http.use_ssl = true

    request = Net::HTTP::Post.new(url)
    request['Authorization'] = 'Bearer {token}'
    request['Content-Type'] = 'application/json'
    request.body = <<REQUEST_BODY
    {
      "to_folder_id": "FAF2lZtloor",
      "item_id": "Msd59349ff"
    }
    REQUEST_BODY

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

## Success response

If successful, the endpoint returns the status code `204 No content` without a response body.

## 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 responses

##### The provided ID is not a valid folder ID.

```json
{
  "code": "invalid_field",
  "message": "The folder id `{value}` is invalid"
}
```

##### The item ID does not match any known ID format.

```json
{
  "code": "invalid_field",
  "message": "The item id `{value}` is invalid"
}
```

##### The target folder has reached its size limit

```json
{
  "code": "quota_exceeded",
  "message": "Target folder has reached size limit"
}
```

##### The item exists in multiple folders

```json
{
  "code": "item_in_multiple_folders",
  "message": "The item lives in multiple folders. Please move it to the new folder via Canva Desktop App or Canva in a browser."
}
```

##### The destination folder can't be the same as the item being moved

```json
{
  "code": "bad_request_params",
  "message": "'to_folder_id' and 'item_id' cannot be the same."
}
```

### 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 responses

##### Not allowed to access the folder

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

##### Not allowed to move the Uploads folder

```json
{
  "code": "permission_denied",
  "message": "Not allowed to move the Uploads folder."
}
```

##### Shared designs are not allowed in the root folder

```json
{
  "code": "permission_denied",
  "message": "Shared designs are not allowed in the root folder"
}
```

##### Not allowed to access the folder item

```json
{
  "code": "permission_denied",
  "message": "Not allowed to access folder item '{itemId}'"
}
```

### 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 responses

##### The folder was not found

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

##### The destination folder was not found

```json
{
  "code": "folder_not_found",
  "message": "To folder {folderId} not found"
}
```

##### The folder item was not found

```json
{
  "code": "not_found",
  "message": "Folder item '{itemId}' not found"
}
```